sdx-cli 0.3.0 → 0.3.1

package/README.md

@@ -20,6 +20,7 @@
   <a href="#install-from-npm">Install from npm</a> •
   <a href="#one-command-setup">One-Command Setup</a> •
   <a href="#architecture-pack-org--service-deep-dives">Architecture Pack</a> •
+  <a href="#canonical-root-readme-generation">Canonical README</a> •
   <a href="#daily-workflow">Daily Workflow</a> •
   <a href="#for-codex-agents">For Codex Agents</a> •
   <a href="#release-process">Release Process</a>
@@ -133,6 +134,7 @@ From your SDX workspace root:
 ./scripts/sdx contracts extract --map platform-core
 ./scripts/sdx docs generate --map platform-core
 ./scripts/sdx architecture generate --map platform-core
+./scripts/sdx docs readme --map platform-core
 ```
 
 For planning and rollout:
@@ -175,6 +177,70 @@ Use overrides to:
 - suppress incorrect inferred edges,
 - attach service owner/criticality/business context metadata.
 
+### Canonical Root README Generation
+Generate a complete root `README.md` as the canonical onboarding and architecture overview for your org workspace.
+
+```bash
+# generate/update root README.md
+./scripts/sdx docs readme --map platform-core
+
+# write to a different output file
+./scripts/sdx docs readme --map platform-core --output ARCHITECTURE.md
+
+# check mode for CI (non-zero on stale sources, missing sources, or README drift)
+./scripts/sdx docs readme --map platform-core --check
+
+# dry-run preview with unified diff and freshness summary
+./scripts/sdx docs readme --map platform-core --dry-run
+
+# selective sections
+./scripts/sdx docs readme --map platform-core \
+  --include what_is_this_system,architecture_glance,service_catalog \
+  --exclude glossary
+```
+
+Supported section IDs (baseline order):
+- `what_is_this_system`
+- `architecture_glance`
+- `service_catalog`
+- `critical_flows`
+- `event_async_topology`
+- `contracts_index`
+- `repository_index`
+- `environments_deployment`
+- `data_stores_boundaries`
+- `security_compliance`
+- `local_dev_contribution`
+- `runbooks_escalation`
+- `adr_index`
+- `glossary`
+- `changelog_metadata`
+
+README config file support (first existing file wins):
+- `.sdx/readme.config.json`
+- `.sdx/readme.config.yaml`
+- `.sdx/readme.config.yml`
+
+Config capabilities:
+- section toggles (`sections.include`, `sections.exclude`, `sections.enabled`)
+- repo include/exclude filters (`repos.include`, `repos.exclude`)
+- domain grouping (`domainGroups`)
+- owner/team overrides (`ownerTeamOverrides`)
+- diagram behavior (`diagram.autoGenerateMissing`, `diagram.includeC4Links`)
+- custom intro text (`customIntro`)
+- stale threshold override in hours (`staleThresholdHours`, default `72`)
+
+Manual content preservation:
+- generated wrappers: `<!-- SDX:SECTION:<id>:START --> ... <!-- SDX:SECTION:<id>:END -->`
+- preserved manual blocks: `<!-- SDX:SECTION:<id>:MANUAL:START --> ... <!-- SDX:SECTION:<id>:MANUAL:END -->`
+
+CI automation example:
+- copy [`docs/examples/readme-refresh.yml`](./docs/examples/readme-refresh.yml) into your consumer workspace repo under `.github/workflows/`.
+- set repo/org variables:
+  - `SDX_ORG` (required)
+  - `SDX_MAP` (optional, defaults to `all-services` in the workflow)
+- the workflow runs `repo sync`, `map build`, `contracts extract`, `docs generate`, and `docs readme`, then opens a PR.
+
 ## Cross-Repo Tech-Lead PRs (Spec-System Native)
 Use this flow when SDX should create real `CC-*` contract-change PRs in downstream repos that have spec-system initialized.
 
@@ -233,7 +299,8 @@ Use this minimal runbook when an agent needs architecture context quickly:
 3. `./scripts/sdx map build <map-id>`
 4. `./scripts/sdx contracts extract --map <map-id>`
 5. `./scripts/sdx architecture generate --map <map-id>`
-6. `./scripts/sdx codex run <task-type> --map <map-id> --input <file>`
+6. `./scripts/sdx docs readme --map <map-id>`
+7. `./scripts/sdx codex run <task-type> --map <map-id> --input <file>`
 
 Where outputs land:
 - `maps/<map-id>/service-map.json|md|mmd`
@@ -260,7 +327,7 @@ sdx prompt
 
 sdx architecture generate|validate
 sdx contracts extract
-sdx docs generate
+sdx docs generate|readme
 sdx plan review
 sdx service propose
 sdx handoff draft

package/dist/commands/docs/readme.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const readme_1 = require("../../lib/readme");
+const project_1 = require("../../lib/project");
+class DocsReadmeCommand extends core_1.Command {
+    static description = 'Generate or validate the canonical root README from SDX artifacts';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        output: core_1.Flags.string({ required: false, default: 'README.md', description: 'README output path' }),
+        check: core_1.Flags.boolean({ required: false, default: false, description: 'Check mode (no writes, non-zero on stale/missing/diff)' }),
+        'dry-run': core_1.Flags.boolean({ required: false, default: false, description: 'Preview mode (no writes, print unified diff + summary)' }),
+        include: core_1.Flags.string({
+            required: false,
+            description: 'Comma-separated section IDs to include (baseline order preserved)',
+        }),
+        exclude: core_1.Flags.string({
+            required: false,
+            description: 'Comma-separated section IDs to exclude (applied after include; exclude wins)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(DocsReadmeCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const includeSections = (0, readme_1.parseReadmeSectionList)(flags.include);
+        const excludeSections = (0, readme_1.parseReadmeSectionList)(flags.exclude);
+        const result = (0, readme_1.generateReadme)({
+            mapId: flags.map,
+            db: context.db,
+            cwd: context.cwd,
+            output: flags.output,
+            includeSections,
+            excludeSections,
+            check: flags.check,
+            dryRun: flags['dry-run'],
+        });
+        const status = result.checkPassed ? 'ok' : 'error';
+        (0, project_1.recordRun)(context.db, 'docs_readme', status, flags.map, {
+            outputPath: result.outputPath,
+            sections: result.sections,
+            changed: result.changed,
+            stale: result.stale,
+            staleSources: result.staleSources.map((source) => source.label),
+            missingSources: result.missingSources.map((source) => source.label),
+            dryRun: flags['dry-run'],
+            check: flags.check,
+        });
+        context.db.close();
+        this.log(result.summary);
+        if (result.diff && result.diff.trim().length > 0) {
+            this.log('');
+            this.log(result.diff.trimEnd());
+        }
+        if (flags.check && !result.checkPassed) {
+            this.error('README check failed: stale/missing sources or content drift detected.', { exit: 1 });
+        }
+        if (!flags.check && !flags['dry-run']) {
+            this.log(`Wrote README: ${result.outputPath}`);
+        }
+    }
+}
+exports.default = DocsReadmeCommand;