[GH-ISSUE #650] feat: Expand `asc docs` to embed and surface user-facing documentation guides #182

New issue

Closed

opened 2026-02-26 21:33:55 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 21:33:55 +03:00

Owner

Originally created by @rudrankriyam on GitHub (Feb 18, 2026).
Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/650

Originally assigned to: @rudrankriyam on GitHub.

Problem

The docs/ directory contains valuable documentation (workflows, API quirks, CLI reference), but none of it is accessible to users who install asc as a compiled binary. These files only exist in the source repository.

Today, asc docs is a command group with a single subcommand (init), which writes an embedded ASC.md reference into the user's repo. That embedding pattern works — but only one document uses it.

Meanwhile, guides like WORKFLOWS.md (how to write workflow definitions) and API_NOTES.md (date formats, report types, sandbox quirks) are invisible to anyone who didn't clone the source repo. Users who need this information have to search the GitHub repo or guess.

Current state

The docs/ directory contains:

File	Content	Audience
`WORKFLOWS.md`	Workflow definition format, security model, examples	Users
`API_NOTES.md`	API quirks: date formats, finance reports, sandbox testers	Users
`GO_STANDARDS.md`	Go coding conventions (formatting, naming, error handling)	Contributors only
`TESTING.md`	Testing patterns (table-driven tests, mocking, coverage)	Contributors only
`CONTRIBUTING.md`	Git workflow, CLI structure, adding commands (agent-focused)	Contributors only
`openapi/README.md`	How to update the OpenAPI snapshot	Contributors only

The embedded template (internal/cli/docs/templates/ASC.md) already uses //go:embed successfully.

Proposal

1) Categorize docs as external (user-facing) vs internal (contributor-only)

External — embed in the binary and surface via asc docs:

ASC.md (already embedded via asc init / asc docs init)
WORKFLOWS.md — users need this to write .asc/workflow.json definitions
API_NOTES.md — users need this for date formats, report types, region codes, sandbox quirks

Internal — remain in the source repo only:

GO_STANDARDS.md — Go coding conventions (only relevant to contributors)
TESTING.md — test patterns and coverage expectations (only relevant to contributors)
CONTRIBUTING.md — git workflow and CLI structure for agents/contributors
openapi/README.md — snapshot maintenance instructions

The boundary: if a user of the CLI (not a contributor to the CLI) would benefit from reading it, it's external.

2) Add `asc docs list` subcommand

List all available embedded documentation guides:

$ asc docs list
workflows    Workflow definition format, security model, and examples
api-notes    API quirks: date formats, finance reports, sandbox testers
reference    ASC CLI command reference (also available via 'asc init')

Output should support --output json|table|markdown like other commands.

3) Add `asc docs show <name>` subcommand

Print an embedded guide to stdout:

$ asc docs show workflows
# Workflows

`asc workflow` lets you define named, multi-step automation sequences...

Behavior:

Prints the full markdown content to stdout
Unknown name → exit code 2 with available names listed on stderr
No name argument → usage help (same as asc docs show --help)

4) Embed external docs using `//go:embed`

Extend the existing internal/cli/docs/templates/ directory (or a sibling internal/cli/docs/guides/) with the external docs. Use Go's embed package to bundle them into the binary at compile time, same pattern as ASC.md today.

Each guide gets a slug (e.g. workflows, api-notes, reference) and metadata (short description).

5) Keep `asc docs init` and `asc init` unchanged

The existing init behavior (write ASC.md into the user's repo) stays as-is. asc docs show reference would print the same content to stdout without writing a file — complementary, not conflicting.

Suggested guide slugs

Slug	Source file	Description
`reference`	`templates/ASC.md`	ASC CLI command reference
`workflows`	`WORKFLOWS.md`	Workflow definition format, security model, and examples
`api-notes`	`API_NOTES.md`	API quirks: date formats, finance reports, sandbox testers

Future guides (e.g. authentication, environment-variables) can be added using the same pattern.

Implementation notes

Register list and show as subcommands of DocsCommand() in internal/cli/docs/docs.go
Use //go:embed in a guides registry file (similar to template.go)
show should write to stdout (not stderr) so it can be piped: asc docs show workflows | less
list should respect --output for structured output
Internal docs (GO_STANDARDS.md, TESTING.md, CONTRIBUTING.md) should NOT be embedded — they stay in docs/ for contributors who have the source repo
Copy external docs into the embed directory (or use //go:embed with relative paths to docs/) at build time or as source-of-truth copies in the templates directory

Acceptance criteria

asc docs list prints available guides with slugs and descriptions
asc docs list --output json returns structured JSON
asc docs show workflows prints WORKFLOWS.md content to stdout
asc docs show api-notes prints API_NOTES.md content to stdout
asc docs show reference prints ASC.md content to stdout
asc docs show unknown exits with code 2 and lists available guides on stderr
asc docs show (no argument) shows usage help
Internal docs (GO_STANDARDS.md, TESTING.md, CONTRIBUTING.md, openapi/README.md) are NOT embedded
asc docs init and asc init behavior unchanged
Tests: internal/cli/cmdtest coverage for list, show, and error cases
make test passes

Future considerations

asc docs show could support --format plain to strip markdown formatting for terminal readability
Additional guides (e.g. authentication, environment-variables, troubleshooting) can be added over time
asc docs search <query> for full-text search across embedded guides (stretch goal)

Originally created by @rudrankriyam on GitHub (Feb 18, 2026). Original GitHub issue: https://github.com/rudrankriyam/App-Store-Connect-CLI/issues/650 Originally assigned to: @rudrankriyam on GitHub. ## Problem The `docs/` directory contains valuable documentation (workflows, API quirks, CLI reference), but none of it is accessible to users who install `asc` as a compiled binary. These files only exist in the source repository. Today, `asc docs` is a command group with a single subcommand (`init`), which writes an embedded `ASC.md` reference into the user's repo. That embedding pattern works — but only one document uses it. Meanwhile, guides like `WORKFLOWS.md` (how to write workflow definitions) and `API_NOTES.md` (date formats, report types, sandbox quirks) are invisible to anyone who didn't clone the source repo. Users who need this information have to search the GitHub repo or guess. ## Current state The `docs/` directory contains: | File | Content | Audience | |------|---------|----------| | `WORKFLOWS.md` | Workflow definition format, security model, examples | **Users** | | `API_NOTES.md` | API quirks: date formats, finance reports, sandbox testers | **Users** | | `GO_STANDARDS.md` | Go coding conventions (formatting, naming, error handling) | Contributors only | | `TESTING.md` | Testing patterns (table-driven tests, mocking, coverage) | Contributors only | | `CONTRIBUTING.md` | Git workflow, CLI structure, adding commands (agent-focused) | Contributors only | | `openapi/README.md` | How to update the OpenAPI snapshot | Contributors only | The embedded template (`internal/cli/docs/templates/ASC.md`) already uses `//go:embed` successfully. ## Proposal ### 1) Categorize docs as external (user-facing) vs internal (contributor-only) **External** — embed in the binary and surface via `asc docs`: - `ASC.md` (already embedded via `asc init` / `asc docs init`) - `WORKFLOWS.md` — users need this to write `.asc/workflow.json` definitions - `API_NOTES.md` — users need this for date formats, report types, region codes, sandbox quirks **Internal** — remain in the source repo only: - `GO_STANDARDS.md` — Go coding conventions (only relevant to contributors) - `TESTING.md` — test patterns and coverage expectations (only relevant to contributors) - `CONTRIBUTING.md` — git workflow and CLI structure for agents/contributors - `openapi/README.md` — snapshot maintenance instructions The boundary: if a user of the CLI (not a contributor to the CLI) would benefit from reading it, it's external. ### 2) Add `asc docs list` subcommand List all available embedded documentation guides: ```bash $ asc docs list workflows Workflow definition format, security model, and examples api-notes API quirks: date formats, finance reports, sandbox testers reference ASC CLI command reference (also available via 'asc init') ``` Output should support `--output json|table|markdown` like other commands. ### 3) Add `asc docs show <name>` subcommand Print an embedded guide to stdout: ```bash $ asc docs show workflows # Workflows `asc workflow` lets you define named, multi-step automation sequences... ``` Behavior: - Prints the full markdown content to stdout - Unknown name → exit code 2 with available names listed on stderr - No name argument → usage help (same as `asc docs show --help`) ### 4) Embed external docs using `//go:embed` Extend the existing `internal/cli/docs/templates/` directory (or a sibling `internal/cli/docs/guides/`) with the external docs. Use Go's `embed` package to bundle them into the binary at compile time, same pattern as `ASC.md` today. Each guide gets a slug (e.g. `workflows`, `api-notes`, `reference`) and metadata (short description). ### 5) Keep `asc docs init` and `asc init` unchanged The existing `init` behavior (write `ASC.md` into the user's repo) stays as-is. `asc docs show reference` would print the same content to stdout without writing a file — complementary, not conflicting. ## Suggested guide slugs | Slug | Source file | Description | |------|------------|-------------| | `reference` | `templates/ASC.md` | ASC CLI command reference | | `workflows` | `WORKFLOWS.md` | Workflow definition format, security model, and examples | | `api-notes` | `API_NOTES.md` | API quirks: date formats, finance reports, sandbox testers | Future guides (e.g. `authentication`, `environment-variables`) can be added using the same pattern. ## Implementation notes - Register `list` and `show` as subcommands of `DocsCommand()` in `internal/cli/docs/docs.go` - Use `//go:embed` in a guides registry file (similar to `template.go`) - `show` should write to stdout (not stderr) so it can be piped: `asc docs show workflows | less` - `list` should respect `--output` for structured output - Internal docs (`GO_STANDARDS.md`, `TESTING.md`, `CONTRIBUTING.md`) should NOT be embedded — they stay in `docs/` for contributors who have the source repo - Copy external docs into the embed directory (or use `//go:embed` with relative paths to `docs/`) at build time or as source-of-truth copies in the templates directory ## Acceptance criteria - [ ] `asc docs list` prints available guides with slugs and descriptions - [ ] `asc docs list --output json` returns structured JSON - [ ] `asc docs show workflows` prints `WORKFLOWS.md` content to stdout - [ ] `asc docs show api-notes` prints `API_NOTES.md` content to stdout - [ ] `asc docs show reference` prints `ASC.md` content to stdout - [ ] `asc docs show unknown` exits with code 2 and lists available guides on stderr - [ ] `asc docs show` (no argument) shows usage help - [ ] Internal docs (`GO_STANDARDS.md`, `TESTING.md`, `CONTRIBUTING.md`, `openapi/README.md`) are NOT embedded - [ ] `asc docs init` and `asc init` behavior unchanged - [ ] Tests: `internal/cli/cmdtest` coverage for `list`, `show`, and error cases - [ ] `make test` passes ## Future considerations - `asc docs show` could support `--format plain` to strip markdown formatting for terminal readability - Additional guides (e.g. `authentication`, `environment-variables`, `troubleshooting`) can be added over time - `asc docs search <query>` for full-text search across embedded guides (stretch goal)