sdx-cli 0.2.1

package/dist/commands/map/build.js

@@ -0,0 +1,44 @@
+"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 fs_1 = require("../../lib/fs");
+const mapBuilder_1 = require("../../lib/mapBuilder");
+const project_1 = require("../../lib/project");
+const repoRegistry_1 = require("../../lib/repoRegistry");
+const scope_1 = require("../../lib/scope");
+class MapBuildCommand extends core_1.Command {
+    static description = 'Generate map artifacts (markdown, mermaid, json) for a named map';
+    static args = {
+        mapId: core_1.Args.string({ required: true, description: 'Map identifier' }),
+    };
+    async run() {
+        const { args } = await this.parse(MapBuildCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const scope = (0, scope_1.loadScopeManifest)(args.mapId, context.cwd);
+        (0, scope_1.saveScopeManifest)(scope, context.cwd);
+        const repoMap = new Map((0, repoRegistry_1.listAllRepos)(context.db).map((repo) => [repo.name, repo]));
+        const artifact = (0, mapBuilder_1.buildServiceMapArtifact)(args.mapId, scope, repoMap);
+        const mapDir = node_path_1.default.join(context.cwd, 'maps', args.mapId);
+        const jsonPath = node_path_1.default.join(mapDir, 'service-map.json');
+        const mdPath = node_path_1.default.join(mapDir, 'service-map.md');
+        const mmdPath = node_path_1.default.join(mapDir, 'service-map.mmd');
+        (0, fs_1.writeJsonFile)(jsonPath, artifact);
+        (0, fs_1.writeTextFile)(mdPath, (0, mapBuilder_1.renderServiceMapMarkdown)(artifact));
+        (0, fs_1.writeTextFile)(mmdPath, (0, mapBuilder_1.renderServiceMapMermaid)(artifact));
+        (0, project_1.recordRun)(context.db, 'map_build', 'ok', args.mapId, {
+            repos: artifact.repos.length,
+            nodes: artifact.nodes.length,
+            edges: artifact.edges.length,
+        });
+        context.db.close();
+        this.log(`Built map '${args.mapId}'.`);
+        this.log(`JSON: ${jsonPath}`);
+        this.log(`Markdown: ${mdPath}`);
+        this.log(`Mermaid: ${mmdPath}`);
+    }
+}
+exports.default = MapBuildCommand;

package/dist/commands/map/create.js

@@ -0,0 +1,40 @@
+"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 project_1 = require("../../lib/project");
+const scope_1 = require("../../lib/scope");
+const repoRegistry_1 = require("../../lib/repoRegistry");
+class MapCreateCommand extends core_1.Command {
+    static description = 'Create a named service map scope from discovered repositories';
+    static flags = {
+        org: core_1.Flags.string({ char: 'o', required: true, description: 'GitHub organization to source repositories from' }),
+    };
+    static args = {
+        mapId: core_1.Args.string({ required: true, description: 'Map identifier' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(MapCreateCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const repos = (0, repoRegistry_1.listReposByOrg)(context.db, flags.org);
+        if (repos.length === 0) {
+            throw new Error(`No repositories found for org '${flags.org}'. Run 'sdx repo sync --org ${flags.org}' first.`);
+        }
+        (0, project_1.ensureMapDir)(args.mapId, context.cwd);
+        const manifest = (0, scope_1.createScopeManifest)(args.mapId, flags.org, repos.map((repo) => repo.name), context.cwd);
+        const archivedOrFork = repos.filter((repo) => repo.archived || repo.fork).map((repo) => repo.name);
+        manifest.explicitExclude = [...new Set([...manifest.explicitExclude, ...archivedOrFork])].sort((a, b) => a.localeCompare(b));
+        const scopePath = (0, scope_1.saveScopeManifest)(manifest, context.cwd);
+        const readmePath = node_path_1.default.join(node_path_1.default.dirname(scopePath), 'README.md');
+        this.log(`Map created: ${args.mapId}`);
+        this.log(`Scope manifest: ${scopePath}`);
+        this.log(`Map directory: ${node_path_1.default.dirname(scopePath)}`);
+        this.log(`Create notes in: ${readmePath}`);
+        (0, project_1.recordRun)(context.db, 'map_create', 'ok', args.mapId, { org: flags.org, discovered: repos.length });
+        context.db.close();
+    }
+}
+exports.default = MapCreateCommand;

package/dist/commands/map/exclude.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const project_1 = require("../../lib/project");
+const scope_1 = require("../../lib/scope");
+class MapExcludeCommand extends core_1.Command {
+    static description = 'Add repositories to explicit map exclude overrides';
+    static args = {
+        mapId: core_1.Args.string({ required: true, description: 'Map identifier' }),
+        repos: core_1.Args.string({ required: true, multiple: true, description: 'Repository names (space- or comma-separated)' }),
+    };
+    async run() {
+        const { args } = await this.parse(MapExcludeCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const repos = args.repos
+            .flatMap((entry) => entry.split(','))
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        const updated = (0, scope_1.applyScopeChange)(args.mapId, 'exclude', repos, 'Manual exclude via CLI', context.cwd);
+        (0, project_1.recordRun)(context.db, 'map_exclude', 'ok', args.mapId, { repos });
+        context.db.close();
+        this.log(`Updated '${args.mapId}'. Effective repos: ${updated.effective.length}`);
+    }
+}
+exports.default = MapExcludeCommand;

package/dist/commands/map/include.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const project_1 = require("../../lib/project");
+const scope_1 = require("../../lib/scope");
+class MapIncludeCommand extends core_1.Command {
+    static description = 'Add repositories to explicit map include overrides';
+    static args = {
+        mapId: core_1.Args.string({ required: true, description: 'Map identifier' }),
+        repos: core_1.Args.string({ required: true, multiple: true, description: 'Repository names (space- or comma-separated)' }),
+    };
+    async run() {
+        const { args } = await this.parse(MapIncludeCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const repos = args.repos
+            .flatMap((entry) => entry.split(','))
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        const updated = (0, scope_1.applyScopeChange)(args.mapId, 'include', repos, 'Manual include via CLI', context.cwd);
+        (0, project_1.recordRun)(context.db, 'map_include', 'ok', args.mapId, { repos });
+        context.db.close();
+        this.log(`Updated '${args.mapId}'. Effective repos: ${updated.effective.length}`);
+    }
+}
+exports.default = MapIncludeCommand;

package/dist/commands/map/remove-override.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const project_1 = require("../../lib/project");
+const scope_1 = require("../../lib/scope");
+class MapRemoveOverrideCommand extends core_1.Command {
+    static description = 'Remove include/exclude overrides for repositories in a map';
+    static args = {
+        mapId: core_1.Args.string({ required: true, description: 'Map identifier' }),
+        repos: core_1.Args.string({ required: true, multiple: true, description: 'Repository names (space- or comma-separated)' }),
+    };
+    async run() {
+        const { args } = await this.parse(MapRemoveOverrideCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const repos = args.repos
+            .flatMap((entry) => entry.split(','))
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+        const updated = (0, scope_1.applyScopeChange)(args.mapId, 'remove_override', repos, 'Override removed via CLI', context.cwd);
+        (0, project_1.recordRun)(context.db, 'map_remove_override', 'ok', args.mapId, { repos });
+        context.db.close();
+        this.log(`Updated '${args.mapId}'. Effective repos: ${updated.effective.length}`);
+    }
+}
+exports.default = MapRemoveOverrideCommand;

package/dist/commands/map/status.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const project_1 = require("../../lib/project");
+const scope_1 = require("../../lib/scope");
+class MapStatusCommand extends core_1.Command {
+    static description = 'Show current map scope and overrides';
+    static args = {
+        mapId: core_1.Args.string({ required: true, description: 'Map identifier' }),
+    };
+    async run() {
+        const { args } = await this.parse(MapStatusCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const scope = (0, scope_1.loadScopeManifest)(args.mapId, context.cwd);
+        context.db.close();
+        this.log(`Map: ${scope.mapId}`);
+        this.log(`Org: ${scope.org}`);
+        this.log(`Discovered: ${scope.discovered.length}`);
+        this.log(`Explicit include: ${scope.explicitInclude.length}`);
+        this.log(`Explicit exclude: ${scope.explicitExclude.length}`);
+        this.log(`Effective: ${scope.effective.length}`);
+        if (scope.explicitInclude.length > 0) {
+            this.log(`Include overrides: ${scope.explicitInclude.join(', ')}`);
+        }
+        if (scope.explicitExclude.length > 0) {
+            this.log(`Exclude overrides: ${scope.explicitExclude.join(', ')}`);
+        }
+    }
+}
+exports.default = MapStatusCommand;

package/dist/commands/migrate/artifacts.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@oclif/core");
+const artifactMigration_1 = require("../../lib/artifactMigration");
+const constants_1 = require("../../lib/constants");
+const project_1 = require("../../lib/project");
+class MigrateArtifactsCommand extends core_1.Command {
+    static description = 'Migrate artifact files to the current schema version';
+    static flags = {
+        from: core_1.Flags.string({ required: false, description: 'Optional source version hint' }),
+    };
+    async run() {
+        const { flags } = await this.parse(MigrateArtifactsCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const targets = [];
+        const roots = [node_path_1.default.join(context.cwd, 'maps'), node_path_1.default.join(context.cwd, 'plans'), node_path_1.default.join(context.cwd, 'handoffs'), node_path_1.default.join(context.cwd, 'codex')];
+        for (const root of roots) {
+            if (!node_fs_1.default.existsSync(root)) {
+                continue;
+            }
+            const stack = [root];
+            while (stack.length > 0) {
+                const current = stack.pop();
+                for (const entry of node_fs_1.default.readdirSync(current, { withFileTypes: true })) {
+                    const nextPath = node_path_1.default.join(current, entry.name);
+                    if (entry.isDirectory()) {
+                        stack.push(nextPath);
+                        continue;
+                    }
+                    if (entry.name.endsWith('.json') && (0, artifactMigration_1.isManagedArtifactPath)(context.cwd, nextPath)) {
+                        targets.push(nextPath);
+                    }
+                }
+            }
+        }
+        let migrated = 0;
+        for (const filePath of targets) {
+            try {
+                const data = JSON.parse(node_fs_1.default.readFileSync(filePath, 'utf8'));
+                if (!(0, artifactMigration_1.isManagedArtifactPayload)(data)) {
+                    continue;
+                }
+                if (data.schemaVersion === constants_1.SCHEMA_VERSION) {
+                    continue;
+                }
+                data.schemaVersion = constants_1.SCHEMA_VERSION;
+                data.migratedAt = new Date().toISOString();
+                if (flags.from) {
+                    data.migratedFrom = flags.from;
+                }
+                node_fs_1.default.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+                migrated += 1;
+            }
+            catch {
+                continue;
+            }
+        }
+        (0, project_1.recordRun)(context.db, 'migrate_artifacts', 'ok', undefined, { migrated, scanned: targets.length });
+        context.db.close();
+        this.log(`Migrated ${migrated} artifact files to schema ${constants_1.SCHEMA_VERSION}.`);
+    }
+}
+exports.default = MigrateArtifactsCommand;

package/dist/commands/plan/review.js

@@ -0,0 +1,60 @@
+"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 fs_1 = require("../../lib/fs");
+const mapBuilder_1 = require("../../lib/mapBuilder");
+const planReview_1 = require("../../lib/planReview");
+const project_1 = require("../../lib/project");
+const repoRegistry_1 = require("../../lib/repoRegistry");
+const scope_1 = require("../../lib/scope");
+class PlanReviewCommand extends core_1.Command {
+    static description = 'Review a proposed service plan against current architecture';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        plan: core_1.Flags.string({ required: true, description: 'Path to plan file (markdown or text)' }),
+    };
+    static args = {
+        target: core_1.Args.string({ required: false, description: 'Reserved positional arg' }),
+    };
+    async run() {
+        const { flags } = await this.parse(PlanReviewCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const scope = (0, scope_1.loadScopeManifest)(flags.map, context.cwd);
+        const repoMap = new Map((0, repoRegistry_1.listAllRepos)(context.db).map((repo) => [repo.name, repo]));
+        const mapPath = node_path_1.default.join(context.cwd, 'maps', flags.map, 'service-map.json');
+        const fallbackMap = (0, mapBuilder_1.buildServiceMapArtifact)(flags.map, scope, repoMap);
+        let selectedMap = fallbackMap;
+        if ((0, fs_1.fileExists)(mapPath)) {
+            try {
+                const serviceMap = (0, fs_1.readJsonFile)(mapPath);
+                if (serviceMap?.nodes?.length > 0) {
+                    selectedMap = serviceMap;
+                }
+            }
+            catch {
+                selectedMap = fallbackMap;
+            }
+        }
+        const review = (0, planReview_1.reviewPlan)(flags.map, flags.plan, scope, selectedMap);
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const outJsonPath = node_path_1.default.join(context.cwd, 'plans', 'reviews', `${stamp}-${flags.map}.json`);
+        const outMdPath = node_path_1.default.join(context.cwd, 'plans', 'reviews', `${stamp}-${flags.map}.md`);
+        (0, fs_1.writeJsonFile)(outJsonPath, review);
+        (0, fs_1.writeTextFile)(outMdPath, (0, planReview_1.renderPlanReviewMarkdown)(review));
+        (0, project_1.recordRun)(context.db, 'plan_review', review.accepted ? 'ok' : 'error', flags.map, {
+            missingNfrs: review.missingNfrs,
+            impactedRepos: review.impactedRepos,
+            output: outMdPath,
+        });
+        context.db.close();
+        this.log(`Plan review written to ${outMdPath}`);
+        if (!review.accepted) {
+            throw new Error(`Plan review failed required NFR checks: ${review.missingNfrs.join(', ')}`);
+        }
+    }
+}
+exports.default = PlanReviewCommand;

package/dist/commands/prompt.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const promptParser_1 = require("../lib/promptParser");
+const scope_1 = require("../lib/scope");
+const workflows_1 = require("../lib/workflows");
+const project_1 = require("../lib/project");
+class PromptCommand extends core_1.Command {
+    static description = 'Parse natural-language map instructions with preview and optional apply';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        apply: core_1.Flags.boolean({ required: false, default: false, description: 'Apply the parsed action' }),
+    };
+    static args = {
+        instruction: core_1.Args.string({ required: true, description: 'Natural language instruction' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(PromptCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const scope = (0, scope_1.loadScopeManifest)(flags.map, context.cwd);
+        const knownRepos = [...new Set([...scope.discovered, ...scope.explicitInclude, ...scope.explicitExclude])];
+        const intent = (0, promptParser_1.parsePromptIntent)(args.instruction, knownRepos);
+        this.log((0, promptParser_1.renderPromptPreview)(intent));
+        if (!flags.apply) {
+            this.log('Preview only. Re-run with --apply to persist changes.');
+            context.db.close();
+            return;
+        }
+        if (intent.action === 'include' || intent.action === 'exclude') {
+            if (intent.repos.length === 0) {
+                throw new Error('No known repositories were parsed from prompt. Use explicit map commands or mention exact repo names.');
+            }
+            const updated = (0, scope_1.applyScopeChange)(flags.map, intent.action, intent.repos, `${intent.action} via prompt`, context.cwd);
+            (0, project_1.recordRun)(context.db, 'prompt_apply', 'ok', flags.map, {
+                action: intent.action,
+                repos: intent.repos,
+                effectiveCount: updated.effective.length,
+            });
+            this.log(`Applied ${intent.action} to map '${flags.map}'.`);
+            context.db.close();
+            return;
+        }
+        if (intent.action === 'build') {
+            const result = (0, workflows_1.buildMapArtifacts)(flags.map, context.db, context.cwd);
+            (0, project_1.recordRun)(context.db, 'prompt_build', 'ok', flags.map, result);
+            this.log(`Built map '${flags.map}' via prompt.`);
+            context.db.close();
+            return;
+        }
+        if (intent.action === 'status') {
+            const scope = (0, scope_1.loadScopeManifest)(flags.map, context.cwd);
+            this.log(`Map ${scope.mapId}: effective=${scope.effective.length}, include=${scope.explicitInclude.length}, exclude=${scope.explicitExclude.length}`);
+            (0, project_1.recordRun)(context.db, 'prompt_status', 'ok', flags.map);
+            context.db.close();
+            return;
+        }
+        (0, project_1.recordRun)(context.db, 'prompt_unknown', 'error', flags.map, { instruction: args.instruction });
+        context.db.close();
+        throw new Error('Unable to determine a deterministic action from prompt. Use explicit map commands.');
+    }
+}
+exports.default = PromptCommand;

package/dist/commands/publish/notices.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const publishContracts_1 = require("../../lib/publishContracts");
+const project_1 = require("../../lib/project");
+class PublishNoticesCommand extends core_1.Command {
+    static description = 'Publish cross-repo spec-system Contract Change PRs to target repositories';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        'source-repo': core_1.Flags.string({
+            required: true,
+            description: 'Source repository name or owner/repo',
+        }),
+        'contract-change-id': core_1.Flags.string({
+            required: false,
+            description: 'Optional single contract change filter (example: CC-101)',
+        }),
+        'dry-run': core_1.Flags.boolean({
+            default: false,
+            description: 'Preview actions without writing branches, files, or PRs',
+        }),
+        'max-targets': core_1.Flags.integer({
+            required: false,
+            description: 'Maximum number of pending targets to publish in this run',
+        }),
+        'notice-type': core_1.Flags.string({
+            required: false,
+            default: 'contract',
+            options: ['contract', 'service'],
+            description: 'Notice generation mode',
+        }),
+        plan: core_1.Flags.string({
+            required: false,
+            description: 'Required for --notice-type service. Path to structured service plan markdown.',
+        }),
+        ready: core_1.Flags.boolean({
+            default: false,
+            description: 'Create ready PRs instead of draft PRs',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(PublishNoticesCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const tokenEnv = context.config.github.tokenEnv;
+        const token = process.env[tokenEnv];
+        if (!flags['dry-run'] && !token) {
+            throw new Error(`Missing ${tokenEnv}. Set it before running publish notices.`);
+        }
+        if (flags['notice-type'] === 'service' && !flags.plan) {
+            throw new Error('`--plan <file>` is required when --notice-type service is used.');
+        }
+        const result = await (0, publishContracts_1.publishNotices)({
+            db: context.db,
+            mapId: flags.map,
+            sourceRepo: flags['source-repo'],
+            contractChangeId: flags['contract-change-id'],
+            dryRun: flags['dry-run'],
+            maxTargets: flags['max-targets'],
+            noticeType: flags['notice-type'],
+            planPath: flags.plan,
+            ready: flags.ready,
+            githubToken: token,
+            cwd: context.cwd,
+        });
+        const status = result.totals.failed > 0 ? 'error' : 'ok';
+        (0, project_1.recordRun)(context.db, 'publish_notices', status, flags.map, {
+            sourceRepo: result.sourceRepo,
+            contractChangeId: result.contractChangeId,
+            noticeType: result.noticeType,
+            planPath: result.planPath,
+            dryRun: result.dryRun,
+            created: result.totals.created,
+            updated: result.totals.updated,
+            skipped: result.totals.skipped,
+            failed: result.totals.failed,
+            sourceSyncPrUrls: result.sourceSyncPrUrls,
+        });
+        context.db.close();
+        this.log(`Mode=${result.noticeType} Targets: created=${result.totals.created}, updated=${result.totals.updated}, skipped=${result.totals.skipped}, failed=${result.totals.failed}`);
+        for (const contract of result.contracts) {
+            for (const target of contract.targetResults) {
+                this.log(`${contract.contractChangeId} ${target.targetRepoInput}: ${target.status} (${target.stateBefore} -> ${target.stateAfter})${target.prUrl ? ` ${target.prUrl}` : ''}${target.reason ? ` - ${target.reason}` : ''}`);
+            }
+        }
+        this.log(`Artifact JSON: ${result.artifactJsonPath}`);
+        this.log(`Artifact Markdown: ${result.artifactMarkdownPath}`);
+        if (result.failFastStoppedAt) {
+            this.log(`Fail-fast stop: ${result.failFastStoppedAt}`);
+        }
+        if (result.sourceSyncPrUrls.length > 0) {
+            this.log(`Source Sync PRs: ${result.sourceSyncPrUrls.join(', ')}`);
+        }
+        if (result.totals.failed > 0) {
+            this.error(`publish notices completed with ${result.totals.failed} failed target(s).`, { exit: 1 });
+        }
+    }
+}
+exports.default = PublishNoticesCommand;

package/dist/commands/publish/sync.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const project_1 = require("../../lib/project");
+const publishContracts_1 = require("../../lib/publishContracts");
+class PublishSyncCommand extends core_1.Command {
+    static description = 'Refresh downstream PR lifecycle state and sync source CC artifacts';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+        'source-repo': core_1.Flags.string({
+            required: true,
+            description: 'Source repository name or owner/repo',
+        }),
+        'contract-change-id': core_1.Flags.string({
+            required: false,
+            description: 'Optional single contract change filter (example: CC-101)',
+        }),
+        'dry-run': core_1.Flags.boolean({
+            default: false,
+            description: 'Preview sync state transitions without writing source sync PRs',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(PublishSyncCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const tokenEnv = context.config.github.tokenEnv;
+        const token = process.env[tokenEnv];
+        if (!flags['dry-run'] && !token) {
+            throw new Error(`Missing ${tokenEnv}. Set it before running publish sync.`);
+        }
+        const result = await (0, publishContracts_1.publishSync)({
+            db: context.db,
+            mapId: flags.map,
+            sourceRepo: flags['source-repo'],
+            contractChangeId: flags['contract-change-id'],
+            dryRun: flags['dry-run'],
+            githubToken: token,
+            cwd: context.cwd,
+        });
+        const status = result.totals.failed > 0 ? 'error' : 'ok';
+        (0, project_1.recordRun)(context.db, 'publish_sync', status, flags.map, {
+            sourceRepo: result.sourceRepo,
+            contractChangeId: result.contractChangeId,
+            dryRun: result.dryRun,
+            updated: result.totals.updated,
+            skipped: result.totals.skipped,
+            failed: result.totals.failed,
+            sourceSyncPrUrls: result.sourceSyncPrUrls,
+        });
+        context.db.close();
+        this.log(`Targets: updated=${result.totals.updated}, skipped=${result.totals.skipped}, failed=${result.totals.failed}`);
+        for (const contract of result.contracts) {
+            for (const target of contract.targetResults) {
+                this.log(`${contract.contractChangeId} ${target.repo}: ${target.status} (${target.stateBefore} -> ${target.stateAfter})${target.prUrl ? ` ${target.prUrl}` : ''}${target.reason ? ` - ${target.reason}` : ''}`);
+            }
+        }
+        this.log(`Artifact JSON: ${result.artifactJsonPath}`);
+        this.log(`Artifact Markdown: ${result.artifactMarkdownPath}`);
+        if (result.sourceSyncPrUrls.length > 0) {
+            this.log(`Source Sync PRs: ${result.sourceSyncPrUrls.join(', ')}`);
+        }
+        if (result.totals.failed > 0) {
+            this.error(`publish sync completed with ${result.totals.failed} failed target(s).`, { exit: 1 });
+        }
+    }
+}
+exports.default = PublishSyncCommand;

package/dist/commands/publish/wiki.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+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");
+class PublishWikiCommand extends core_1.Command {
+    static description = 'Export docs-first artifacts to a wiki-friendly directory';
+    static flags = {
+        map: core_1.Flags.string({ required: true, description: 'Map identifier' }),
+    };
+    async run() {
+        const { flags } = await this.parse(PublishWikiCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const sourceFiles = [
+            node_path_1.default.join(context.cwd, 'maps', flags.map, 'service-map.md'),
+            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 wikiDir = node_path_1.default.join(context.cwd, 'wiki-export', flags.map);
+        (0, fs_1.ensureDir)(wikiDir);
+        for (const source of sourceFiles) {
+            if (!node_fs_1.default.existsSync(source)) {
+                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);
+        }
+        (0, project_1.recordRun)(context.db, 'publish_wiki', 'ok', flags.map, { wikiDir });
+        context.db.close();
+        this.log(`Wiki export generated at ${wikiDir}`);
+    }
+}
+exports.default = PublishWikiCommand;

package/dist/commands/repo/add.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const core_1 = require("@oclif/core");
+const project_1 = require("../../lib/project");
+const repoRegistry_1 = require("../../lib/repoRegistry");
+class RepoAddCommand extends core_1.Command {
+    static description = 'Register a local clone path for a repository';
+    static flags = {
+        name: core_1.Flags.string({ char: 'n', required: true, description: 'Repository name' }),
+        path: core_1.Flags.string({ char: 'p', required: true, description: 'Local path to repository clone' }),
+        org: core_1.Flags.string({ char: 'o', required: false, description: 'Organization override' }),
+    };
+    async run() {
+        const { flags } = await this.parse(RepoAddCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        if (!node_fs_1.default.existsSync(flags.path)) {
+            throw new Error(`Local path does not exist: ${flags.path}`);
+        }
+        const repo = (0, repoRegistry_1.setLocalRepoPath)(context.db, flags.name, flags.path, flags.org ?? context.config.github.defaultOrg);
+        (0, project_1.recordRun)(context.db, 'repo_add', 'ok', undefined, { name: repo.name, localPath: repo.localPath });
+        context.db.close();
+        this.log(`Registered local repo '${repo.name}' at ${repo.localPath}`);
+    }
+}
+exports.default = RepoAddCommand;

package/dist/commands/repo/sync.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const github_1 = require("../../lib/github");
+const project_1 = require("../../lib/project");
+const repoRegistry_1 = require("../../lib/repoRegistry");
+class RepoSyncCommand extends core_1.Command {
+    static description = 'Sync repository inventory from a GitHub organization';
+    static flags = {
+        org: core_1.Flags.string({ char: 'o', required: false, description: 'GitHub org (defaults to config.github.defaultOrg)' }),
+    };
+    async run() {
+        const { flags } = await this.parse(RepoSyncCommand);
+        const context = (0, project_1.loadProject)(process.cwd());
+        const org = flags.org ?? context.config.github.defaultOrg;
+        if (!org) {
+            throw new Error('No organization provided. Use --org or set one via `sdx bootstrap org`.');
+        }
+        const token = process.env[context.config.github.tokenEnv];
+        if (!token) {
+            throw new Error(`Missing GitHub token. Set ${context.config.github.tokenEnv}.`);
+        }
+        const repos = await (0, github_1.fetchOrgRepos)(org, token);
+        (0, repoRegistry_1.upsertRepos)(context.db, repos);
+        (0, project_1.recordRun)(context.db, 'repo_sync', 'ok', undefined, { org, count: repos.length });
+        context.db.close();
+        this.log(`Synced ${repos.length} repositories for org '${org}'.`);
+    }
+}
+exports.default = RepoSyncCommand;