sdx-cli 0.2.2 → 0.3.1

package/README.md

@@ -19,6 +19,8 @@
 <p align="center">
   <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>
@@ -131,6 +133,8 @@ 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:
@@ -147,6 +151,96 @@ For Codex:
 ./scripts/sdx codex run implementation-plan --map platform-core --input ./plans/new-service.md
 ```
 
+### Architecture Pack (Org + Service Deep Dives)
+Generate an executive-ready architecture pack from your initialized consumer workspace:
+
+```bash
+# full pack (org-level + per-service docs/diagrams)
+./scripts/sdx architecture generate --map platform-core
+
+# org-level only
+./scripts/sdx architecture generate --map platform-core --depth org
+
+# targeted service rebuild
+./scripts/sdx architecture generate --map platform-core --service payments-api
+
+# explicit validation pass (override integrity + completeness checks)
+./scripts/sdx architecture validate --map platform-core
+```
+
+Override source of truth:
+- `maps/<map-id>/architecture-overrides.json`
+
+Use overrides to:
+- declare hidden or external dependencies,
+- assert missing relationships,
+- 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.
 
@@ -204,11 +298,17 @@ Use this minimal runbook when an agent needs architecture context quickly:
 2. `./scripts/sdx map status <map-id>`
 3. `./scripts/sdx map build <map-id>`
 4. `./scripts/sdx contracts extract --map <map-id>`
-5. `./scripts/sdx codex run <task-type> --map <map-id> --input <file>`
+5. `./scripts/sdx architecture generate --map <map-id>`
+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`
 - `maps/<map-id>/contracts.json|md`
+- `maps/<map-id>/architecture/model.json|validation.json`
+- `maps/<map-id>/architecture-overrides.json`
+- `docs/architecture/<map-id>/index.md`
+- `docs/architecture/<map-id>/services/*.md`
 - `codex/context-packs/*.json`
 - `codex/runs/*.md|json`
 
@@ -225,8 +325,9 @@ sdx repo add
 sdx map create|include|exclude|remove-override|status|build
 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/architecture/generate.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const architecture_1 = require("../../lib/architecture");
+const project_1 = require("../../lib/project");
+const workflows_1 = require("../../lib/workflows");
+class ArchitectureGenerateCommand extends core_1.Command {
+    static description = 'Generate architecture pack artifacts and diagrams for a map';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        depth: core_1.Flags.string({
+            required: false,
+            options: ['org', 'full'],
+            default: 'full',
+            description: 'Generation depth: org-only or full (org + per-service packs)',
+        }),
+        service: core_1.Flags.string({
+            required: false,
+            description: 'Generate only one service deep-dive (service id/repo name)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ArchitectureGenerateCommand);
+        if (flags.depth === 'org' && flags.service) {
+            throw new Error('Cannot use --service with --depth org. Use --depth full for targeted service generation.');
+        }
+        const context = (0, project_1.loadProject)(process.cwd());
+        const mapArtifacts = (0, workflows_1.buildMapArtifacts)(flags.map, context.db, context.cwd);
+        const contractArtifacts = (0, workflows_1.extractContractArtifacts)(flags.map, context.db, context.cwd);
+        const docsArtifacts = (0, workflows_1.generateDocsArtifacts)(flags.map, context.db, context.cwd);
+        const result = (0, architecture_1.generateArchitecturePack)({
+            mapId: flags.map,
+            db: context.db,
+            cwd: context.cwd,
+            depth: flags.depth,
+            serviceId: flags.service,
+        });
+        (0, project_1.recordRun)(context.db, 'architecture_generate', result.validation.valid ? 'ok' : 'error', flags.map, {
+            depth: flags.depth,
+            service: flags.service,
+            generatedServices: result.generatedServices.length,
+            validation: result.validation,
+            modelPath: result.modelPath,
+            indexDocPath: result.indexDocPath,
+            baseline: {
+                mapArtifacts,
+                contractArtifacts,
+                docsArtifacts,
+            },
+        });
+        context.db.close();
+        this.log(`Generated architecture pack for map '${flags.map}'.`);
+        this.log(`Model: ${result.modelPath}`);
+        this.log(`Overrides: ${result.overridesPath}`);
+        this.log(`Baseline service map: ${result.baselineArtifacts.serviceMapPath}`);
+        this.log(`Baseline contracts: ${result.baselineArtifacts.contractsPath}`);
+        this.log(`Baseline architecture doc: ${result.baselineArtifacts.architectureDocPath}`);
+        if (result.indexDocPath) {
+            this.log(`Architecture index: ${result.indexDocPath}`);
+        }
+        if (result.generatedServices.length > 0) {
+            this.log(`Service deep dives: ${result.generatedServices.length}`);
+        }
+        this.log(`Validation: ${result.validation.valid ? 'pass' : 'fail'} (errors=${result.validation.errors.length}, warnings=${result.validation.warnings.length})`);
+        if (!result.validation.valid) {
+            this.error('Architecture validation failed. Resolve override/model issues and rerun.', { exit: 1 });
+        }
+    }
+}
+exports.default = ArchitectureGenerateCommand;

package/dist/commands/architecture/validate.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@oclif/core");
+const architecture_1 = require("../../lib/architecture");
+const fs_1 = require("../../lib/fs");
+const project_1 = require("../../lib/project");
+class ArchitectureValidateCommand extends core_1.Command {
+    static description = 'Validate architecture model completeness and override integrity for a map';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+    };
+    async run() {
+        const { flags } = await this.parse(ArchitectureValidateCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const result = (0, architecture_1.validateArchitecture)({
+            mapId: flags.map,
+            db: context.db,
+            cwd: context.cwd,
+        });
+        const outDir = node_path_1.default.join(context.cwd, 'maps', flags.map, 'architecture');
+        const jsonPath = node_path_1.default.join(outDir, 'validation.json');
+        const mdPath = node_path_1.default.join(outDir, 'validation.md');
+        (0, fs_1.writeJsonFile)(jsonPath, result);
+        const lines = [
+            `# Architecture Validation: ${flags.map}`,
+            '',
+            `- Generated: ${result.generatedAt}`,
+            `- Valid: ${result.valid ? 'yes' : 'no'}`,
+            `- Errors: ${result.errors.length}`,
+            `- Warnings: ${result.warnings.length}`,
+            '',
+        ];
+        if (result.errors.length > 0) {
+            lines.push('## Errors');
+            lines.push('');
+            for (const err of result.errors) {
+                lines.push(`- ${err}`);
+            }
+            lines.push('');
+        }
+        if (result.warnings.length > 0) {
+            lines.push('## Warnings');
+            lines.push('');
+            for (const warning of result.warnings) {
+                lines.push(`- ${warning}`);
+            }
+            lines.push('');
+        }
+        (0, fs_1.writeTextFile)(mdPath, `${lines.join('\n')}\n`);
+        (0, project_1.recordRun)(context.db, 'architecture_validate', result.valid ? 'ok' : 'error', flags.map, {
+            validationPath: jsonPath,
+            errorCount: result.errors.length,
+            warningCount: result.warnings.length,
+            stats: result.stats,
+        });
+        context.db.close();
+        this.log(`Validated architecture for map '${flags.map}'.`);
+        this.log(`JSON: ${jsonPath}`);
+        this.log(`Markdown: ${mdPath}`);
+        this.log(`Result: ${result.valid ? 'pass' : 'fail'}`);
+        if (!result.valid) {
+            this.error('Architecture validation failed. Resolve errors and rerun.', { exit: 1 });
+        }
+    }
+}
+exports.default = ArchitectureValidateCommand;

package/dist/commands/bootstrap/quick.js

@@ -70,6 +70,7 @@ class BootstrapQuickCommand extends core_1.Command {
             this.log('- ./scripts/sdx map create all-services --org <org>');
             this.log('- ./scripts/sdx map build all-services');
         }
+        this.log('- ./scripts/sdx architecture generate --map all-services');
         if (result.warnings.length > 0) {
             this.log('');
             this.log('Warnings:');

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;

package/dist/commands/publish/wiki.js

@@ -8,6 +8,19 @@ const node_path_1 = __importDefault(require("node:path"));
 const core_1 = require("@oclif/core");
 const fs_1 = require("../../lib/fs");
 const project_1 = require("../../lib/project");
+function copyRecursive(source, target) {
+    const stat = node_fs_1.default.statSync(source);
+    if (stat.isDirectory()) {
+        (0, fs_1.ensureDir)(target);
+        const entries = node_fs_1.default.readdirSync(source, { withFileTypes: true });
+        for (const entry of entries) {
+            copyRecursive(node_path_1.default.join(source, entry.name), node_path_1.default.join(target, entry.name));
+        }
+        return;
+    }
+    const body = node_fs_1.default.readFileSync(source, 'utf8');
+    (0, fs_1.writeTextFile)(target, body);
+}
 class PublishWikiCommand extends core_1.Command {
     static description = 'Export docs-first artifacts to a wiki-friendly directory';
     static flags = {
@@ -21,6 +34,9 @@ class PublishWikiCommand extends core_1.Command {
             node_path_1.default.join(context.cwd, 'maps', flags.map, 'contracts.md'),
             node_path_1.default.join(context.cwd, 'docs', 'architecture', `${flags.map}.md`),
         ];
+        const sourceDirs = [
+            node_path_1.default.join(context.cwd, 'docs', 'architecture', flags.map),
+        ];
         const wikiDir = node_path_1.default.join(context.cwd, 'wiki-export', flags.map);
         (0, fs_1.ensureDir)(wikiDir);
         for (const source of sourceFiles) {
@@ -28,8 +44,14 @@ class PublishWikiCommand extends core_1.Command {
                 continue;
             }
             const target = node_path_1.default.join(wikiDir, node_path_1.default.basename(source));
-            const body = node_fs_1.default.readFileSync(source, 'utf8');
-            (0, fs_1.writeTextFile)(target, body);
+            copyRecursive(source, target);
+        }
+        for (const source of sourceDirs) {
+            if (!node_fs_1.default.existsSync(source)) {
+                continue;
+            }
+            const target = node_path_1.default.join(wikiDir, node_path_1.default.basename(source));
+            copyRecursive(source, target);
         }
         (0, project_1.recordRun)(context.db, 'publish_wiki', 'ok', flags.map, { wikiDir });
         context.db.close();

package/dist/commands/status.js

@@ -29,7 +29,8 @@ class StatusCommand extends core_1.Command {
             const mapDir = node_path_1.default.join(mapsDir, mapId);
             const hasScope = (0, fs_1.fileExists)(node_path_1.default.join(mapDir, 'scope.json'));
             const hasServiceMap = (0, fs_1.fileExists)(node_path_1.default.join(mapDir, 'service-map.json'));
-            this.log(`- ${mapId}: scope=${hasScope ? 'yes' : 'no'}, service-map=${hasServiceMap ? 'yes' : 'no'}`);
+            const hasArchitectureModel = (0, fs_1.fileExists)(node_path_1.default.join(mapDir, 'architecture', 'model.json'));
+            this.log(`- ${mapId}: scope=${hasScope ? 'yes' : 'no'}, service-map=${hasServiceMap ? 'yes' : 'no'}, architecture=${hasArchitectureModel ? 'yes' : 'no'}`);
         }
         context.db.close();
     }