sdx-cli 0.3.0 → 0.3.2

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,76 @@ 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.
+
+What `docs readme` now does:
+- traverses Markdown docs across repos in map scope (`README*`, `docs/**`, ADRs, runbooks),
+- infers service purpose, interfaces, async behavior, deployment cues, and operating notes,
+- combines that with map/contracts/architecture artifacts,
+- writes a clean narrative README (no SDX section marker blocks in output).
+
+For best results:
+- register local clones for repos you care about (`repo add`) so SDX can deeply scan docs,
+- set `GITHUB_TOKEN` to let SDX fetch Markdown docs for repos without local clones.
+
+```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/missing required artifacts or README drift)
+./scripts/sdx docs readme --map platform-core --check
+
+# dry-run preview with unified diff + readiness 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`)
+
+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 +305,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 +333,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 = await (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/lib/github.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchOrgRepos = fetchOrgRepos;
 exports.ensureOrgRepo = ensureOrgRepo;
+exports.fetchRepositoryMarkdownDocs = fetchRepositoryMarkdownDocs;
 async function fetchOrgRepos(org, token) {
     const { Octokit } = await import('@octokit/rest');
     const octokit = new Octokit({ auth: token });
@@ -50,3 +51,85 @@ async function ensureOrgRepo(org, repoName, token) {
         htmlUrl: created.data.html_url ?? undefined,
     };
 }
+function markdownPathPriority(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower === 'readme.md' || lower.endsWith('/readme.md') || lower.endsWith('/readme.mdx')) {
+        return 0;
+    }
+    if (lower.includes('/docs/architecture/') || lower.includes('/architecture/')) {
+        return 1;
+    }
+    if (lower.includes('/docs/api/') || lower.includes('/api/')) {
+        return 2;
+    }
+    if (lower.includes('/docs/')) {
+        return 3;
+    }
+    return 4;
+}
+function isIgnoredPath(filePath) {
+    const lower = filePath.toLowerCase();
+    return (lower.includes('/node_modules/') ||
+        lower.includes('/dist/') ||
+        lower.includes('/build/') ||
+        lower.includes('/.next/') ||
+        lower.includes('/coverage/') ||
+        lower.includes('/vendor/'));
+}
+function toBlobUrl(owner, repo, branch, filePath) {
+    const encodedPath = filePath
+        .split('/')
+        .map((part) => encodeURIComponent(part))
+        .join('/');
+    return `https://github.com/${owner}/${repo}/blob/${encodeURIComponent(branch)}/${encodedPath}`;
+}
+async function fetchRepositoryMarkdownDocs(options) {
+    const { Octokit } = await import('@octokit/rest');
+    const octokit = new Octokit({ auth: options.token });
+    const maxFiles = options.maxFiles ?? 30;
+    const maxBytesPerFile = options.maxBytesPerFile ?? 120_000;
+    const tree = await octokit.rest.git.getTree({
+        owner: options.owner,
+        repo: options.repo,
+        tree_sha: options.defaultBranch,
+        recursive: 'true',
+    });
+    const markdownFiles = (tree.data.tree ?? [])
+        .filter((entry) => Boolean(entry.path && entry.type))
+        .map((entry) => ({ path: entry.path, type: entry.type }))
+        .filter((entry) => entry.type === 'blob')
+        .map((entry) => entry.path)
+        .filter((filePath) => /\.(md|mdx)$/i.test(filePath))
+        .filter((filePath) => !isIgnoredPath(filePath))
+        .sort((a, b) => {
+        const priorityDelta = markdownPathPriority(a) - markdownPathPriority(b);
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        return a.localeCompare(b);
+    })
+        .slice(0, maxFiles);
+    const docs = [];
+    for (const filePath of markdownFiles) {
+        const response = await octokit.rest.repos.getContent({
+            owner: options.owner,
+            repo: options.repo,
+            path: filePath,
+            ref: options.defaultBranch,
+        });
+        if (Array.isArray(response.data) || response.data.type !== 'file' || !response.data.content) {
+            continue;
+        }
+        const raw = Buffer.from(response.data.content, 'base64').toString('utf8');
+        const body = raw.slice(0, maxBytesPerFile);
+        if (body.trim().length === 0) {
+            continue;
+        }
+        docs.push({
+            path: filePath,
+            body,
+            referenceUrl: toBlobUrl(options.owner, options.repo, options.defaultBranch, filePath),
+        });
+    }
+    return docs;
+}