@codesummary/cli 0.1.0

package/README.md

@@ -0,0 +1,280 @@
+# CodeSummary CLI
+
+Dependency-free Node CLI for submitting a local workspace to CodeSummary.
+The hosted flow can log in with OAuth, create or link a private docs site,
+upload a local source snapshot, and start knowledge updates from the repo
+directory.
+
+## Install
+
+Before npm publication, install from the private GitHub repo:
+
+```bash
+npm install -g github:CodeSummaryAI/codesummary-cli
+```
+
+After npm publication:
+
+```bash
+npm install -g @codesummary/cli
+```
+
+Then run it from a repo:
+
+```bash
+codesummary login --api-url https://dashboard.codesummary.io
+codesummary
+```
+
+Bare `codesummary` is the normal workflow. It inspects the current repo and
+guides the user through creating or updating the CodeSummary knowledge source.
+
+## Install Smoke
+
+From this repo, verify the packaged binary path before release:
+
+```bash
+npm test
+npm run test:package
+npm run release:check
+```
+
+`test:package` runs `npm pack`, installs the tarball into a temporary project,
+and verifies that the installed `codesummary` binary starts correctly inside a
+repo workspace.
+
+## Commands
+
+```bash
+codesummary
+codesummary new ./my-service --api-url https://dashboard.codesummary.io
+codesummary login --api-url https://dashboard.codesummary.io
+codesummary config set apiUrl https://dashboard.codesummary.io
+codesummary config get apiUrl
+codesummary config clear apiUrl
+codesummary link --site-token <csp_token> --api-url https://dashboard.codesummary.io --name my-repo
+codesummary manifest
+codesummary diff
+codesummary export --output ./codesummary-export
+codesummary export --output s3://my-bucket/path --include-archive
+codesummary generate --provider codex --output ./docs
+codesummary generate --provider openai --api-key-env OPENAI_API_KEY --output ./docs
+codesummary configure --provider codex --output ./docs
+codesummary generate
+codesummary submit --depth standard
+codesummary status
+codesummary submit --depth standard --wait
+codesummary version
+codesummary update
+```
+
+Bare `codesummary` starts the interactive hosted workflow. It inspects the
+current directory, OAuth state, linked site, last submitted manifest, and local
+diff, then offers the right action:
+
+- fresh repo: create a private docs site and generate knowledge, or check setup without generation
+- existing repo with changes: update knowledge, check setup without generation, or show the diff
+- existing repo with no changes: refresh anyway, check setup without generation, or exit
+
+`new` initializes a local CodeSummary workspace. It creates
+`.codesummary/config.json`, stores the source name/API URL, and never deletes
+existing files. If you point it at a non-empty directory, pass `--force` to
+confirm you want to initialize that directory in place.
+
+`config` manages persistent workspace defaults:
+
+```bash
+codesummary config list
+codesummary config set apiUrl https://dashboard.codesummary.io
+codesummary config set sourceName my-service
+codesummary config set depth standard
+codesummary config set localGeneration.provider codex
+codesummary config get sourceName
+codesummary config clear depth
+```
+
+Supported keys are `apiUrl`, `sourceName`, `depth`, `site.id`, `site.slug`,
+`site.name`, `localGeneration.provider`, `localGeneration.output`,
+`localGeneration.model`, and `localGeneration.apiKeyEnv`.
+
+`link` verifies the token, records the existing site it belongs to, and stores
+local settings in `.codesummary/config.json`. It does not create a new hosted
+site. The token determines which existing site receives future draft knowledge
+updates.
+
+`submit` creates `.codesummary/manifest.json`, zips the current workspace, uploads it to
+`/api/cli/submit`, links the source to the token's existing site, and enqueues a knowledge job.
+The manifest is sent as separate metadata so CodeSummary can track file hashes
+without relying on the uploaded source archive.
+When the source is linked to an existing site, the backend also enqueues a site
+draft update after the repo knowledge job completes.
+`--no-generate` is a no-spend setup check: it stores manifest metadata and
+source/site linkage, but does not retain the uploaded source archive.
+The CLI stores the last submitted job id in `.codesummary/config.json`, so
+`codesummary status` can check it without passing `--job-id`. Status responses
+include both the repo job and the latest linked site job when a site update is
+running.
+
+After a successful submit, the CLI stores
+`.codesummary/last-submitted-manifest.json`. `codesummary diff` compares the
+current workspace against that baseline and reports added, changed, and removed
+files without uploading anything. Use `--against <manifest.json>` to compare
+against a specific baseline.
+
+`export` creates a local or S3 bundle without calling CodeSummary hosted
+infrastructure. By default it exports only manifest metadata and does not include
+source contents. Pass `--include-archive` only when writing to infrastructure you
+control.
+
+## Auth
+
+Use OAuth for the normal developer workflow:
+
+```bash
+codesummary login --api-url https://dashboard.codesummary.io
+codesummary
+```
+
+Product/site tokens with `write:knowledge` or `write:all` scope are still
+supported for scripted or site-bound workflows.
+
+```bash
+export CODESUMMARY_API_KEY=csp_...
+export CODESUMMARY_API_URL=https://dashboard.codesummary.io
+codesummary link --site-token "$CODESUMMARY_API_KEY" --api-url "$CODESUMMARY_API_URL" --name my-repo
+codesummary submit --name my-repo --depth standard
+codesummary status --wait
+```
+
+## Existing Site Updates
+
+The intended hosted workflow is:
+
+```bash
+codesummary login --api-url https://dashboard.codesummary.io
+codesummary
+```
+
+The local directory becomes a CLI CodeSummary source linked to the selected or
+auto-created private site. Later runs update that same source and can enqueue a
+site draft update when the source knowledge job completes. Publishing the site
+is still a separate dashboard action.
+
+Use `--depth standard` for the default update path. The CLI defaults to
+`standard`; `deep` is available for a more expensive full-context pass.
+
+## Defaults
+
+The archive excludes common build/cache folders and secret files:
+
+- `.git`, `node_modules`, `.next`, `dist`, `build`, `coverage`
+- `.codesummary`, `.env`, `.env.*`, `.npmrc`, `.yarnrc`
+
+The manifest stores file paths, sizes, mtimes, and SHA-256 hashes. It does not
+store file contents.
+
+## Local / BYO Output
+
+For teams that do not want to upload source code to CodeSummary, export a bundle
+locally:
+
+```bash
+codesummary export --output ./codesummary-export
+```
+
+The bundle contains:
+
+- `codesummary-manifest.json`
+- `codesummary-export.json`
+- `README.md`
+
+To include the excluded-source-filtered archive in your own storage, opt in:
+
+```bash
+codesummary export --output s3://my-bucket/codesummary/my-repo --include-archive
+```
+
+S3 output uses the local `aws s3 sync` command and your existing AWS credentials.
+
+## Local Inference
+
+`generate` runs documentation inference locally. It does not upload source code
+or provider credentials to CodeSummary.
+
+Use the local Codex subscription/session:
+
+```bash
+codesummary generate --provider codex --output ./docs
+```
+
+Configure the workspace once, then omit flags:
+
+```bash
+codesummary configure --provider codex --output ./docs
+codesummary generate
+```
+
+Bare `codesummary` is reserved for the hosted interactive workflow. Local
+inference remains explicit with `codesummary generate` so it never spends local
+provider credits by surprise.
+
+Use a provider API key from your local environment:
+
+```bash
+export OPENAI_API_KEY=sk-...
+codesummary generate --provider openai --api-key-env OPENAI_API_KEY --output ./docs
+codesummary configure --provider openai --api-key-env OPENAI_API_KEY --output ./docs
+
+export ANTHROPIC_API_KEY=sk-ant-...
+codesummary generate --provider anthropic --api-key-env ANTHROPIC_API_KEY --output ./docs
+codesummary configure --provider anthropic --api-key-env ANTHROPIC_API_KEY --output ./docs
+```
+
+Safe smoke test without inference:
+
+```bash
+codesummary generate --provider mock --output ./docs
+codesummary generate --provider codex --output ./docs --dry-run
+```
+
+Local generation creates `.codesummary/manifest.json`, builds a local context
+pack from non-secret text files, asks the selected local provider to return a
+strict JSON document set, validates the result, and writes Markdown files to the
+output directory.
+
+Security model:
+
+- Provider keys stay in local environment variables.
+- `.codesummary/config.json` stores the provider choice and env var name, not the
+  provider key value.
+- Codex mode uses the local Codex CLI/session; CodeSummary never sees that
+  credential.
+- Source contents are sent only to the selected local provider.
+- CodeSummary hosted infrastructure is not called by `generate`.
+- Publishing or hosted site updates remain separate commands/flows.
+
+## Staging E2E
+
+For CodeSummary maintainers, the current no-spend staging hosted-flow check is:
+
+```bash
+codesummary login --api-url https://dashboard-staging.codesummary.io
+codesummary whoami
+codesummary diff
+codesummary status
+```
+
+For package/local CLI regressions:
+
+```bash
+npm test
+npm run test:package
+```
+
+Staging defaults to mock generation, so a hosted generation run should complete
+without provider spend but will only produce deterministic test docs. Do not run
+provider-backed staging generation unless the operator explicitly approves the
+credit spend.
+
+The old `scripts/staging-e2e.sh` EC2/SSM flow is retired. Staging no longer has
+that backend EC2 shape.

package/RELEASE.md

@@ -0,0 +1,48 @@
+# CodeSummary CLI Release Checklist
+
+The CLI release gate is intentionally local and no-spend. It does not call the
+hosted generation pipeline or any model provider.
+
+## Required Checks
+
+```bash
+npm test
+npm run test:package
+```
+
+`npm test` verifies command behavior and the interactive TTY flows against a
+fake local dashboard server.
+
+`npm run test:package` runs the install path users depend on:
+
+1. `npm pack`
+2. install the packed tarball into a clean temporary project
+3. execute the installed `codesummary` binary
+4. verify it can run inside a repo workspace and write `.codesummary/manifest.json`
+
+## Install Channels
+
+Before npm publication, install from the private GitHub repo:
+
+```bash
+npm install -g github:CodeSummaryAI/codesummary-cli
+```
+
+After npm publication:
+
+```bash
+npm install -g @codesummary/cli
+```
+
+## Staging Verification
+
+Use staging only after the package checks pass:
+
+```bash
+codesummary login --api-url https://dashboard-staging.codesummary.io
+codesummary whoami
+codesummary
+```
+
+Staging generation is expected to use the no-spend mock path unless the operator
+explicitly enables provider-backed generation.

package/ROADMAP.md

@@ -0,0 +1,242 @@
+# CodeSummary CLI Roadmap
+
+This document tracks the CLI/MCP direction separately from the dashboard and
+backend deployment runbooks.
+
+## Product Goal
+
+Make CodeSummary usable without making GitHub the center of the product.
+GitHub remains an excellent source adapter, but the core abstraction is:
+
+```text
+source -> manifest -> knowledge job -> docs / MCP / export
+```
+
+The CLI should make that flow feel simple:
+
+```bash
+codesummary login
+codesummary
+```
+
+## Implemented Slice
+
+The current staging-validated slice is hosted CLI ingestion:
+
+1. `codesummary new` initializes a safe local CodeSummary workspace without
+   deleting existing files.
+2. `codesummary login` opens the dashboard OAuth flow and stores a refreshable
+   CLI token locally.
+3. `codesummary config get/set/clear` manages persistent workspace defaults.
+4. Bare `codesummary` inspects the current repo, linked site, previous
+   manifest, and local diff, then offers the appropriate action with an arrow
+   selector.
+5. `codesummary submit --wait` writes `.codesummary/manifest.json`, zips the
+   workspace, excludes local config/secrets, and posts the archive plus manifest
+   to `POST /api/cli/submit`.
+6. The dashboard creates or reuses a CLI/manual source with
+   `settings.source_adapter = "cli"`, links it to the token's existing site,
+   uploads the source archive, uploads the manifest JSON, and enqueues a repo
+   knowledge job.
+7. The worker processes the repo knowledge job, deletes the temporary source
+   archive, then enqueues `triggered_by = "cli-site-update"` for the linked
+   site when draft docs already exist.
+8. `codesummary status --wait` follows both the repo job and linked site job.
+9. `codesummary version` / `--version` and `codesummary update` provide the
+   expected global CLI lifecycle surface.
+
+Publishing remains a separate dashboard action.
+
+## Mintlify CLI Parity
+
+Mintlify's public CLI shape is:
+
+```text
+mint new
+mint login/logout/status
+mint config get/set/clear
+mint dev
+mint validate / broken-links / a11y / score
+mint export
+mint version / update
+```
+
+CodeSummary now matches the same lifecycle shape where the product model maps
+cleanly:
+
+- project initialization: `codesummary new`
+- auth/session state: `codesummary login`, `codesummary logout`,
+  `codesummary whoami`
+- persistent defaults: `codesummary config get/set/clear`
+- default workflow: bare `codesummary`
+- validation/diff before upload: `codesummary manifest`, `codesummary diff`
+- export/local mode: `codesummary export`, `codesummary generate`
+- CLI lifecycle: `codesummary version`, `codesummary update`
+
+Intentional differences:
+
+- `mint dev` previews a local docs project. CodeSummary docs are generated from
+  a source workspace and previewed in the hosted site/editor, so a `dev` command
+  should not be added until it can start a real local renderer or open a real
+  hosted draft preview.
+- `mint validate`, `broken-links`, `a11y`, and `score` are docs-site checks.
+  CodeSummary should add equivalent commands after the renderer exposes a local
+  or hosted draft inspection API.
+- `mint automations` maps more closely to future CodeSummary MCP/job tools than
+  to the initial source-ingestion CLI.
+
+## Staging Gate
+
+All CLI workflow changes should be proven against staging before production:
+
+- Dashboard staging: `https://dashboard-staging.codesummary.io`
+- AWS profile: `codesummary-staging`
+- Upload bucket: `codesummary-manual-uploads-staging`
+- Source snapshot bucket: `codesummary-source-snapshots-staging`
+- Docs bucket: `codesummary-docs-staging`
+- Runtime: dashboard OpenNext/Lambda/CloudFront plus backend Lambda/SQS/Batch
+
+Current staging worker mode:
+
+```text
+CODESUMMARY_ENV=staging
+CODESUMMARY_MOCK_GENERATION=true
+```
+
+Mock generation proves upload, manifest storage, worker extraction, repo docs,
+site draft updates, and job status without spending model-provider credits. A
+real provider-backed staging run still requires a staging provider account/key
+with available credits.
+
+No-spend staging check:
+
+```bash
+codesummary login --api-url https://dashboard-staging.codesummary.io
+codesummary whoami
+codesummary status
+```
+
+Provider-backed staging generation should only be run after explicitly stating
+that it will spend provider credits.
+
+## Next Hosted CLI Milestones
+
+1. Add a dashboard UI for minting CLI/site-write tokens with clearer copy.
+2. Add `codesummary sites` and `codesummary link --site <id>` so users can
+   choose among authorized sites instead of only relying on token scope.
+3. Add `codesummary publish` for explicit publish from CLI, guarded by a
+   separate `publish:docs` token scope.
+4. Done: add `codesummary diff` to show what changed since the last submitted
+   manifest or an explicit `--against` manifest.
+
+## Local-Only / BYO Output Mode
+
+Some users will want CodeSummary as a local harness without hosted ingestion.
+That should be a separate mode, not bolted onto hosted submit.
+
+Implemented commands:
+
+```bash
+codesummary export --output ./codesummary-export
+codesummary export --output s3://my-bucket/path --include-archive
+codesummary generate --provider codex --output ./docs
+codesummary generate --provider openai --api-key-env OPENAI_API_KEY --output ./docs
+codesummary generate --provider anthropic --api-key-env ANTHROPIC_API_KEY --output ./docs
+codesummary configure --provider codex --output ./docs
+codesummary generate
+```
+
+`export` creates a manifest bundle without using CodeSummary hosted
+infrastructure. By default, it does not include source contents.
+`--include-archive` is explicit opt-in for BYO local/S3 storage.
+
+`generate` runs local inference. `codex` uses the user's local Codex
+subscription/session through the Codex CLI. API-key providers read the key from a
+local environment variable. CodeSummary does not receive the key and hosted
+infrastructure is not called.
+
+`configure` persists local generation defaults in `.codesummary/config.json`.
+It stores provider choice, output directory, model, and API-key environment
+variable name. It does not store provider key values. Bare `codesummary` is
+reserved for the hosted interactive flow. Local generation stays explicit with
+`codesummary generate` so local provider credits are never spent by surprise.
+
+Design rules:
+
+- no source archive upload to CodeSummary
+- no hosted job unless the user explicitly selects hosted mode
+- optional local export to markdown/json
+- optional BYO S3 output using the user's AWS credentials
+- optional BYO model key through environment variables
+
+This mode should not require a CodeSummary API key unless hosted services are
+used.
+
+Remaining work:
+
+- publish locally generated docs back to a linked CodeSummary site as generated
+  docs, without uploading raw source
+- support direct S3 output for generated docs
+- add richer file-planning and multi-pass generation for large repositories
+- package the CLI as a closed-source distributable binary
+
+## MCP Workflow
+
+MCP should stay thin. It should call the same public API paths that the CLI uses
+instead of owning separate ingestion logic.
+
+Candidate tools:
+
+- `codesummary_link_site`
+- `codesummary_submit_workspace`
+- `codesummary_job_status`
+- `codesummary_diff_manifest`
+- `codesummary_publish_site`
+
+The MCP server should return concrete job ids, site ids, source ids, and next
+commands so coding agents can continue without guessing.
+
+## Manifests, Diffs, And Locks
+
+Manifests should remain first-class:
+
+- every submit sends file path, byte size, mtime, and sha256
+- successful submits save `.codesummary/last-submitted-manifest.json`
+- manifests are stored separately from temporary source archives
+- source archives are temporary and should be deleted after worker processing
+- manifests enable cheap diffing before upload
+
+Concurrency rule:
+
+- one active job per manual source
+- later submits should return a clear conflict with the active job id
+- future UX can offer `--replace-active` only if cancellation is implemented
+
+## Source Adapters
+
+Target adapter model:
+
+```text
+github
+gitlab
+bitbucket
+azure_devops
+cli
+s3
+local_export
+api
+```
+
+Sites should link to one or more sources through a stable source id. The source
+adapter determines how content arrives; sites should not care whether a source
+came from GitHub, CLI, S3, or another provider.
+
+## Security Defaults
+
+- exclude `.codesummary`, `.env*`, npm/yarn auth files, git internals, build
+  caches, and dependency folders from uploads
+- store product tokens only locally unless the user explicitly chooses hosted
+  auth storage
+- never store source archives permanently in hosted mode
+- keep manifests because they do not contain source contents
+- separate knowledge-write, docs-read, and publish scopes