@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/cli/commands/git-remote.d.ts

@@ -0,0 +1,74 @@
+/**
+ * git remote parsing — extract org/repo from `git remote get-url origin`
+ * to substitute into pipeline.yaml during init.
+ *
+ * Why this exists: AISDLC-78 — fresh installs got a literal `your-org`
+ * placeholder in their pipeline.yaml, which made the file unrunnable
+ * until the user noticed and edited it. We auto-detect the org/repo
+ * from the git remote and only fall back to placeholders when no
+ * remote is configured (e.g. a brand-new local-only repo).
+ */
+export interface RemoteInfo {
+    /** Organization or user name. */
+    org: string;
+    /** Repository name (without `.git` suffix). */
+    repo: string;
+    /** Whether the values came from a real git remote (vs the fallback). */
+    detected: boolean;
+}
+/**
+ * Parse a single remote URL into org/repo. Supports:
+ *  - https://github.com/foo/bar.git
+ *  - https://github.com/foo/bar
+ *  - git@github.com:foo/bar.git
+ *  - ssh://git@github.com/foo/bar.git
+ *  - git@gitlab.example.com:group/subgroup/repo.git (org=group, repo=repo)
+ */
+export declare function parseRemoteUrl(url: string): RemoteInfo | null;
+export interface DetectRemoteOptions {
+    /** Override `execSync` for tests. */
+    execImpl?: (cmd: string, opts: {
+        cwd: string;
+        encoding: 'utf-8';
+        stdio: unknown;
+    }) => string;
+    /** Project directory (defaults to process.cwd). */
+    cwd?: string;
+}
+/**
+ * Detect the GitHub-style org/repo from the project's git origin remote.
+ * Returns FALLBACK with detected=false when no remote is configured or
+ * when the URL cannot be parsed.
+ *
+ * The git invocation is hardened against two failure modes (AISDLC-104):
+ *
+ *  1. **cwd inheritance race under parallel test workers.** Every git
+ *     command uses `git -C <cwd>` so the working dir is pinned at the
+ *     git argv level rather than relying solely on `child_process`
+ *     honouring the `cwd:` spawn option. Both should agree, but `git -C`
+ *     is a git-internal contract independent of any subprocess cwd
+ *     inheritance race that can happen when `process.chdir()` is
+ *     interleaved with subprocess spawn under thread/fork pools.
+ *
+ *  2. **Host-repo origin bleed via parent-directory walk-up.** If `cwd`
+ *     contains an invalid `.git` (e.g. an empty directory left by an
+ *     init test setup) git normally walks UP looking for a real `.git`
+ *     and can resolve to an ancestor repository — i.e. when run from
+ *     inside the ai-sdlc-framework checkout the test would silently see
+ *     the framework's own origin rather than the fallback. We defend by
+ *     calling `git rev-parse --show-toplevel` first and confirming the
+ *     reported toplevel matches `cwd` (after symlink resolution). When
+ *     it doesn't, we treat the directory as not-a-repo and return the
+ *     fallback rather than reporting the ancestor's remote. This was
+ *     preferred over `GIT_CEILING_DIRECTORIES` because the ceiling-list
+ *     semantics only block walking INTO the listed dirs, not up FROM
+ *     them — empirically `GIT_CEILING_DIRECTORIES=<cwd>` did not stop
+ *     git from finding a parent repo.
+ */
+export declare function detectGitRemote(opts?: DetectRemoteOptions): RemoteInfo;
+/**
+ * Substitute `your-org` (and optionally `your-repo`) placeholders in a
+ * template body with detected values.
+ */
+export declare function applyRemoteToPipelineYaml(template: string, info: RemoteInfo): string;
+//# sourceMappingURL=git-remote.d.ts.map

package/dist/cli/commands/git-remote.js

@@ -0,0 +1,170 @@
+/**
+ * git remote parsing — extract org/repo from `git remote get-url origin`
+ * to substitute into pipeline.yaml during init.
+ *
+ * Why this exists: AISDLC-78 — fresh installs got a literal `your-org`
+ * placeholder in their pipeline.yaml, which made the file unrunnable
+ * until the user noticed and edited it. We auto-detect the org/repo
+ * from the git remote and only fall back to placeholders when no
+ * remote is configured (e.g. a brand-new local-only repo).
+ */
+import { execSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+const FALLBACK = { org: 'your-org', repo: 'your-repo', detected: false };
+/**
+ * Parse a single remote URL into org/repo. Supports:
+ *  - https://github.com/foo/bar.git
+ *  - https://github.com/foo/bar
+ *  - git@github.com:foo/bar.git
+ *  - ssh://git@github.com/foo/bar.git
+ *  - git@gitlab.example.com:group/subgroup/repo.git (org=group, repo=repo)
+ */
+export function parseRemoteUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    // SSH shorthand: git@host:org/repo.git
+    const sshShort = /^[^@\s]+@[^:\s]+:(.+?)\/([^/\s]+?)(?:\.git)?$/.exec(trimmed);
+    if (sshShort) {
+        return { org: sshShort[1].split('/').slice(-1)[0], repo: sshShort[2], detected: true };
+    }
+    // SSH or HTTPS with a scheme
+    let parsed = null;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed) {
+        const path = parsed.pathname.replace(/^\/+/, '').replace(/\.git$/, '');
+        const segments = path.split('/').filter(Boolean);
+        if (segments.length >= 2) {
+            const repo = segments[segments.length - 1];
+            const org = segments[segments.length - 2];
+            return { org, repo, detected: true };
+        }
+    }
+    return null;
+}
+/**
+ * Detect the GitHub-style org/repo from the project's git origin remote.
+ * Returns FALLBACK with detected=false when no remote is configured or
+ * when the URL cannot be parsed.
+ *
+ * The git invocation is hardened against two failure modes (AISDLC-104):
+ *
+ *  1. **cwd inheritance race under parallel test workers.** Every git
+ *     command uses `git -C <cwd>` so the working dir is pinned at the
+ *     git argv level rather than relying solely on `child_process`
+ *     honouring the `cwd:` spawn option. Both should agree, but `git -C`
+ *     is a git-internal contract independent of any subprocess cwd
+ *     inheritance race that can happen when `process.chdir()` is
+ *     interleaved with subprocess spawn under thread/fork pools.
+ *
+ *  2. **Host-repo origin bleed via parent-directory walk-up.** If `cwd`
+ *     contains an invalid `.git` (e.g. an empty directory left by an
+ *     init test setup) git normally walks UP looking for a real `.git`
+ *     and can resolve to an ancestor repository — i.e. when run from
+ *     inside the ai-sdlc-framework checkout the test would silently see
+ *     the framework's own origin rather than the fallback. We defend by
+ *     calling `git rev-parse --show-toplevel` first and confirming the
+ *     reported toplevel matches `cwd` (after symlink resolution). When
+ *     it doesn't, we treat the directory as not-a-repo and return the
+ *     fallback rather than reporting the ancestor's remote. This was
+ *     preferred over `GIT_CEILING_DIRECTORIES` because the ceiling-list
+ *     semantics only block walking INTO the listed dirs, not up FROM
+ *     them — empirically `GIT_CEILING_DIRECTORIES=<cwd>` did not stop
+ *     git from finding a parent repo.
+ */
+export function detectGitRemote(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const exec = opts.execImpl ?? defaultExec;
+    // Step 1: confirm cwd is a real git repo whose toplevel IS cwd.
+    // If `git rev-parse --show-toplevel` errors OR returns an ancestor,
+    // treat as not-a-repo and return FALLBACK. This is the host-repo
+    // bleed defense: an empty/invalid `.git/` in cwd causes git to walk
+    // UP to a parent repo, and `--show-toplevel` then reports the parent
+    // — comparing realpaths catches it.
+    let toplevel;
+    try {
+        toplevel = exec(`git -C ${shellQuote(cwd)} rev-parse --show-toplevel`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return FALLBACK;
+    }
+    if (!sameDir(toplevel, cwd)) {
+        // git resolved to an ancestor repository — host-repo bleed. The
+        // operator is in a directory that isn't itself a real git root, so
+        // we deliberately do NOT report the ancestor's origin; emit
+        // FALLBACK so init prints the explicit "no git origin remote
+        // detected" message and substitutes `your-org`.
+        return FALLBACK;
+    }
+    // Step 2: ask for the origin URL. If unset (no remote configured)
+    // or unparseable, fall back.
+    let url;
+    try {
+        url = exec(`git -C ${shellQuote(cwd)} remote get-url origin`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return FALLBACK;
+    }
+    const parsed = parseRemoteUrl(url);
+    return parsed ?? FALLBACK;
+}
+/**
+ * Compare two filesystem paths after symlink + canonicalization to
+ * decide whether they refer to the same directory. macOS aliases /tmp
+ * to /private/tmp, so a string compare of `cwd` against the toplevel
+ * git reports would otherwise fail spuriously. Falls back to literal
+ * compare when realpath isn't available (deleted dir, permission).
+ */
+function sameDir(a, b) {
+    const norm = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return p;
+        }
+    };
+    return norm(a) === norm(b);
+}
+/**
+ * Quote a path for safe single-token interpolation into a shell command.
+ * Wraps in single quotes and escapes any embedded single quotes by
+ * closing the quote, emitting an escaped quote, then reopening.
+ */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function defaultExec(cmd, opts) {
+    return execSync(cmd, {
+        cwd: opts.cwd,
+        encoding: opts.encoding,
+        stdio: opts.stdio,
+    });
+}
+/**
+ * Substitute `your-org` (and optionally `your-repo`) placeholders in a
+ * template body with detected values.
+ */
+export function applyRemoteToPipelineYaml(template, info) {
+    // Replace the literal `org: your-org` config line with the detected
+    // org. We deliberately match the exact YAML key shape rather than a
+    // bare token so we don't smear the placeholder if it appears elsewhere.
+    let out = template.replace(/(\borg:\s*)your-org(\b)/g, `$1${info.org}$2`);
+    // If the template ever introduces a repo: placeholder, substitute it too.
+    out = out.replace(/(\brepo:\s*)your-repo(\b)/g, `$1${info.repo}$2`);
+    return out;
+}
+//# sourceMappingURL=git-remote.js.map

package/dist/cli/commands/health.d.ts

@@ -1,5 +1,9 @@
 /**
  * ai-sdlc health — validate config, state store, and adapter connectivity.
+ *
+ * AISDLC-78: surfaces the deferred-state-store wording (handled by the
+ * table formatter) and adds an opt-in `--init-state` flag for users who
+ * want the SQLite database created eagerly rather than on first run.
  */
 import { Command } from 'commander';
 export declare const healthCommand: Command;

package/dist/cli/commands/health.js

@@ -1,18 +1,30 @@
 /**
  * ai-sdlc health — validate config, state store, and adapter connectivity.
+ *
+ * AISDLC-78: surfaces the deferred-state-store wording (handled by the
+ * table formatter) and adds an opt-in `--init-state` flag for users who
+ * want the SQLite database created eagerly rather than on first run.
  */
 import { Command } from 'commander';
+import { join } from 'node:path';
 import { Orchestrator } from '../../orchestrator.js';
 import { formatOutput } from '../formatters/index.js';
 export const healthCommand = new Command('health')
     .description('Check orchestrator health')
     .option('--state <path>', 'SQLite state database path')
+    .option('--init-state', 'Eagerly initialize the SQLite state store (defaults to .ai-sdlc/state.db when --state is omitted)')
     .action(async (opts, cmd) => {
     const globalOpts = cmd.parent?.opts() ?? {};
     const format = globalOpts.format ?? 'table';
+    // When the user opts into eager initialization, default the path to
+    // .ai-sdlc/state.db inside the configured config dir so we don't
+    // litter cwd with an unexpected file.
+    const configDir = globalOpts.config ?? '.ai-sdlc';
+    const statePath = opts.state ??
+        (opts.initState ? join(configDir, 'state.db') : undefined);
     const orchestrator = new Orchestrator({
         configDir: globalOpts.config,
-        statePath: opts.state,
+        statePath,
     });
     try {
         const result = await orchestrator.health();

package/dist/cli/commands/init-features.d.ts

@@ -0,0 +1,208 @@
+/**
+ * `ai-sdlc init` interactive wizard + feature dispatcher (AISDLC-143).
+ *
+ * Per Q4(b) of the operator-ratified quality-gate redesign, `ai-sdlc init`
+ * is a wizard by default with `--yes` for non-interactive (CI/scripts) and
+ * `--with-X` flags for explicit opt-in (`--with-dor`, `--with-attestation`,
+ * `--with-classifier`, `--with-branch-protection`). This module owns:
+ *
+ *   1. The ordered prompt list (resolveFeatureSelection).
+ *   2. The feature-toggle → file-write dispatcher (applyFeatureSelection).
+ *   3. The branch-protection helper (applyBranchProtection) including the
+ *      `--dry-run` JSON-print path required by AC #6.
+ *   4. The "next steps" summary printed at the end of init (AC #5).
+ *
+ * Test surface: every public function takes a small options bag with
+ * injectable side-effect adapters (prompter, writeFile, runCommand) so the
+ * test suite can drive every wizard branch hermetically without spinning
+ * up a TTY or shelling out to `gh`. Production callers in `init.ts` pass
+ * the real adapters.
+ */
+/** Per-feature on/off bits derived from prompts + flags. */
+export interface FeatureSelection {
+    dor: boolean;
+    attestation: boolean;
+    classifier: boolean;
+    branchProtection: boolean;
+}
+/** All feature flags off — used as the initial state before flags + prompts. */
+export declare const NO_FEATURES: FeatureSelection;
+/** All features on — the answer used by `--yes` (accept all defaults). */
+export declare const ALL_FEATURES: FeatureSelection;
+/** Flag-bag controlling wizard behavior (already parsed from argv). */
+export interface WizardFlags {
+    /** `--yes` short-circuits the wizard; treats every prompt as "yes". */
+    yes: boolean;
+    /** `--with-dor` forces the DoR feature on without prompting. */
+    withDor: boolean;
+    /** `--with-attestation` forces attestation infra on without prompting. */
+    withAttestation: boolean;
+    /** `--with-classifier` forces the classifier on without prompting. */
+    withClassifier: boolean;
+    /** `--with-branch-protection` forces branch-protection on without prompting. */
+    withBranchProtection: boolean;
+    /**
+     * `--add <feature>` extends an already-initialized repo with a single
+     * feature without re-prompting. AC #7 (idempotent extension). When set,
+     * the wizard short-circuits to scaffold ONLY this feature.
+     */
+    add?: 'dor' | 'attestation' | 'classifier' | 'branch-protection';
+    /** `--dry-run` — print what would be done, don't write. */
+    dryRun: boolean;
+}
+/**
+ * Single-question prompter contract — accepts a question + default and
+ * returns the user's answer. The production adapter wraps `@inquirer/prompts`
+ * so the user gets a real readline TTY; tests inject a stub that returns
+ * scripted answers without touching stdin.
+ *
+ * Why a single-question primitive instead of "ask all questions at once":
+ * the prompts are conditional in some cases (e.g. branch-protection only
+ * makes sense after the user has chosen which CI gates exist). Keeping
+ * the primitive small lets `resolveFeatureSelection` decide ordering +
+ * skip questions whose answer is already determined by a `--with-X` flag.
+ */
+export type Prompter = (question: string, defaultYes: boolean) => Promise<boolean>;
+/**
+ * Side-effect adapter bag — every part of the dispatcher that touches
+ * disk or shells out goes through this so tests can assert on intents
+ * without mocking `node:fs` globally.
+ */
+export interface FeatureAdapters {
+    /** Resolve to an interactive prompt answer. */
+    prompt: Prompter;
+    /** Write a file. Production = `node:fs.writeFileSync`. */
+    writeFile: (path: string, contents: string) => void;
+    /**
+     * Append `contents` to `path` exactly once: if `sentinel` is already
+     * present in the file, no-op. If the file doesn't exist, behaves like
+     * a write. Used for the husky pre-push sign block + CLAUDE.md pointer
+     * (both of which need to coexist with user-edited content).
+     */
+    appendOnce: (path: string, contents: string, sentinel: string) => 'appended' | 'skipped';
+    /** mkdir -p. Production = `node:fs.mkdirSync({ recursive: true })`. */
+    mkdirp: (path: string) => void;
+    /** Test for path existence. Production = `node:fs.existsSync`. */
+    exists: (path: string) => boolean;
+    /** Run a shell command (used for `gh api`). Production = `execSync`. */
+    runCommand: (cmd: string, args: string[]) => {
+        stdout: string;
+        exitCode: number;
+    };
+    /** Sink for operator-visible output (defaults to console.log). */
+    log: (line: string) => void;
+}
+/**
+ * Build the production adapter bag. Pulled into a factory so tests can
+ * compose a partial override bag (e.g. only override `prompt`) and let
+ * the rest fall through to real disk writes.
+ *
+ * The `prompt` adapter is a lazy import of `@inquirer/prompts.confirm`
+ * so that:
+ *   1. Tests don't pay the import cost when they inject their own stub.
+ *   2. `--yes` runs (which never call `prompt`) don't pay it either.
+ *   3. The orchestrator's runtime `dist/` is smaller for the common case.
+ */
+export declare function buildProductionAdapters(): FeatureAdapters;
+/**
+ * Resolve the per-feature on/off vector by combining (in priority order):
+ *   1. `--add <feature>` — if set, ONLY that feature is on; everything
+ *      else is suppressed (idempotent extension, AC #7).
+ *   2. `--yes` — accept every default (every feature on).
+ *   3. `--with-X` flags — opt-in without prompting.
+ *   4. Interactive prompts for any feature still undetermined.
+ *
+ * Returns a fully-determined FeatureSelection. The dispatcher then writes
+ * exactly the union of features marked true.
+ */
+export declare function resolveFeatureSelection(flags: WizardFlags, adapters: Pick<FeatureAdapters, 'prompt' | 'log'>): Promise<FeatureSelection>;
+/** Return value of `applyFeatureSelection` — what was actually written. */
+export interface ApplyResult {
+    /** Files that were newly created on this run. */
+    created: string[];
+    /** Files that already existed and were left untouched (idempotent). */
+    skipped: string[];
+    /** Files that would have been created if not for `--dry-run`. */
+    wouldCreate: string[];
+    /** Branch-protection result, if attempted. */
+    branchProtection?: BranchProtectionResult;
+}
+/**
+ * Write the union of feature templates into the project dir. AC #4 says
+ * the BASELINE workflow templates (gate workflow) are always written; the
+ * per-feature template sets are written only when their toggle is on.
+ *
+ * Idempotent: any file that already exists at the target path is skipped
+ * with a "skip" log line. This is what makes `--add <feature>` safe to
+ * run on an already-initialized repo (AC #7).
+ */
+export declare function applyFeatureSelection(projectDir: string, selection: FeatureSelection, flags: WizardFlags, adapters: FeatureAdapters): Promise<ApplyResult>;
+export interface BranchProtectionResult {
+    /** Whether the rule was actually applied. False in dry-run. */
+    applied: boolean;
+    /** The PUT body as a JSON string (always populated for visibility). */
+    bodyJson: string;
+    /** Error message from `gh api`, if non-zero exit. */
+    error?: string;
+}
+/**
+ * Recommended branch-protection ruleset for AI-SDLC adopters. AC #1 #4:
+ * the required checks are `ai-sdlc/pr-ready` (the gate aggregator) and
+ * `codecov/patch` (the de facto coverage signal). Other AI-SDLC apps
+ * post their own statuses but they're all rolled into pr-ready.
+ *
+ * The body conforms to the GitHub REST API
+ * `PUT /repos/{owner}/{repo}/branches/{branch}/protection` schema.
+ */
+export declare const RECOMMENDED_BRANCH_PROTECTION_BODY: {
+    required_status_checks: {
+        strict: boolean;
+        contexts: string[];
+    };
+    enforce_admins: boolean;
+    required_pull_request_reviews: {
+        dismiss_stale_reviews: boolean;
+        require_code_owner_reviews: boolean;
+        required_approving_review_count: number;
+    };
+    restrictions: null;
+    allow_force_pushes: boolean;
+    allow_deletions: boolean;
+};
+/**
+ * Apply (or print, in dry-run) the recommended branch protection rule
+ * to the `main` branch of the repo at `projectDir`. AC #6 explicitly
+ * requires that `--dry-run` print the JSON without applying.
+ *
+ * The repo identity (`owner/repo`) is resolved by shelling out to
+ * `gh repo view --json nameWithOwner -q .nameWithOwner`. We could parse
+ * the git remote ourselves (see git-remote.ts) but `gh` already resolves
+ * forks + renames + custom default branches consistently, and the user
+ * needs `gh` on PATH for the PUT to work anyway.
+ */
+export declare function applyBranchProtection(projectDir: string, flags: WizardFlags, adapters: Pick<FeatureAdapters, 'runCommand' | 'log'>): Promise<BranchProtectionResult>;
+/**
+ * Print the structured "next steps" summary at the end of init. AC #5:
+ * the summary must include operator action items conditional on which
+ * features were chosen (e.g. `gh secret set` commands when attestation
+ * was opted in).
+ *
+ * Returns the rendered summary as a string in addition to logging it,
+ * so tests can assert on it without re-stringifying console output.
+ */
+export declare function renderNextSteps(selection: FeatureSelection, result: ApplyResult, adapters: Pick<FeatureAdapters, 'log'>): string;
+/**
+ * The pointer block we append to CLAUDE.md so a freshly-initialized repo's
+ * Claude Code sessions know where to find the AI-SDLC quality-gate docs.
+ * Idempotent — guarded by a sentinel so re-running init doesn't duplicate
+ * the block.
+ */
+export declare const CLAUDE_MD_POINTER = "\n<!-- ai-sdlc:recommendation-pointer -->\n## AI-SDLC quality gate\n\nThis repo is bootstrapped with the AI-SDLC framework. The single PR-ready\nmerge gate is `ai-sdlc/pr-ready` (see `.github/workflows/ai-sdlc-gate.yml`).\nRun `ai-sdlc health` to verify your local config; see\n`docs/operations/init.md` for the adopter guide.\n<!-- end ai-sdlc:recommendation-pointer -->\n";
+/** Sentinel marker used by the CLAUDE.md pointer for idempotency. */
+export declare const CLAUDE_MD_SENTINEL = "<!-- ai-sdlc:recommendation-pointer -->";
+/**
+ * Append the recommendation pointer to CLAUDE.md (or create the file if
+ * missing). Idempotent: if the sentinel is already present we no-op.
+ */
+export declare function ensureClaudeMdPointer(projectDir: string, adapters: Pick<FeatureAdapters, 'exists' | 'writeFile' | 'appendOnce' | 'log'>, dryRun: boolean): void;
+//# sourceMappingURL=init-features.d.ts.map