@sdd-method/maintain-cli 0.1.0 → 0.2.0

package/dist/lib/hooks-seed/copilot.js

@@ -1,167 +0,0 @@
-/**
- * Builders + drift detection for the method-managed GitHub Copilot CLI
- * hooks, per `docs/method/methods/hook-contracts.md` (Hook 1, Hook 2)
- * and the portable contracts in `hook-portable-contract-schema.yaml`.
- *
- * The Copilot CLI surface differs from Claude Code in three ways
- * (per ADR 0141 §4.3 + hook-contracts.md):
- *
- *   1. Hook configs live in per-event JSON files (`.github/hooks/<event>.json`),
- *      not a single settings.json.
- *   2. No per-tool matcher — every `preToolUse` hook fires for every
- *      tool, with in-script filtering instead.
- *   3. Approval semantic is declarative (`approval: deny-on-nonzero`)
- *      rather than exit-code based.
- *
- * Ownership is sentinel-based, same as Claude Code: the `bash` and
- * `powershell` command strings carry `# sdd-method-managed:true`.
- * Adopter-added events in the same `events[]` array lack the sentinel
- * and survive sync.
- */
-import { METHOD_MANAGED_SENTINEL } from "./types.js";
-import { nativeEventName } from "./lifecycle-mapping.js";
-const HARNESS = "github-copilot-cli";
-/** Filename per portable lifecycle class. */
-const HOOK_FILE_BY_PORTABLE = {
-    pre_tool_use: "pre-tool-use.json",
-    session_start: "session-start.json",
-};
-export function copilotHookFilePath(portable) {
-    const name = HOOK_FILE_BY_PORTABLE[portable];
-    if (!name) {
-        throw new Error(`No Copilot CLI hook file mapped for portable class "${portable}"`);
-    }
-    return `.github/hooks/${name}`;
-}
-function withSentinel(command) {
-    if (command.includes(METHOD_MANAGED_SENTINEL))
-        return command;
-    return `${command} ${METHOD_MANAGED_SENTINEL}`;
-}
-/**
- * Hook 1 — `block-edits-to-method-managed-paths` (pre_tool_use).
- * Copilot CLI has no per-tool matcher, so the script
- * (orchestration/scripts/copilot-method-guard.{sh,ps1}) does the
- * filtering on tool name in addition to the path check. Method-side
- * authors the scripts; we just emit the wiring.
- */
-export function buildCopilotPreToolUseEvent() {
-    return {
-        type: nativeEventName(HARNESS, "pre_tool_use"),
-        command: {
-            bash: withSentinel("./orchestration/scripts/copilot-method-guard.sh"),
-            powershell: withSentinel("./orchestration/scripts/copilot-method-guard.ps1"),
-        },
-        timeout_ms: 5000,
-        approval: "deny-on-nonzero",
-    };
-}
-/**
- * Hook 2 — `validate-adr-structure-on-session-start` (session_start).
- * Output is surfaced as session-baseline context; non-blocking
- * (`approval: always-allow`) to match the portable contract's `warn`
- * exit-code semantic.
- */
-export function buildCopilotSessionStartEvent() {
-    return {
-        type: nativeEventName(HARNESS, "session_start"),
-        command: {
-            bash: withSentinel("sdd-cli validate --validator adr-structure 2>&1 | head -20"),
-            powershell: withSentinel("sdd-cli validate --validator adr-structure 2>&1 | Select-Object -First 20"),
-        },
-        timeout_ms: 30000,
-        approval: "always-allow",
-    };
-}
-export function buildMethodManagedCopilotHooks() {
-    return {
-        pre_tool_use: {
-            filePath: copilotHookFilePath("pre_tool_use"),
-            events: [buildCopilotPreToolUseEvent()],
-        },
-        session_start: {
-            filePath: copilotHookFilePath("session_start"),
-            events: [buildCopilotSessionStartEvent()],
-        },
-    };
-}
-/**
- * An event entry is method-managed iff its `command.bash` (or
- * `command.powershell`) carries the sentinel.
- */
-export function isMethodManagedEvent(event) {
-    const bash = typeof event.command?.bash === "string" ? event.command.bash : "";
-    const ps = typeof event.command?.powershell === "string"
-        ? event.command.powershell
-        : "";
-    return (bash.includes(METHOD_MANAGED_SENTINEL) ||
-        ps.includes(METHOD_MANAGED_SENTINEL));
-}
-/**
- * Strip the sentinel and trailing whitespace from a command string so
- * two commands can be compared modulo ownership marker. Symmetric to
- * the Claude Code merge logic.
- */
-function normaliseCommandString(command) {
-    return command.replace(METHOD_MANAGED_SENTINEL, "").trimEnd();
-}
-function eventsEquivalentExcludingSentinel(a, b) {
-    if (a.type !== b.type)
-        return false;
-    if (a.approval !== b.approval)
-        return false;
-    if (a.timeout_ms !== b.timeout_ms)
-        return false;
-    const aBash = a.command?.bash ?? "";
-    const bBash = b.command?.bash ?? "";
-    const aPs = a.command?.powershell ?? "";
-    const bPs = b.command?.powershell ?? "";
-    return (normaliseCommandString(aBash) === normaliseCommandString(bBash) &&
-        normaliseCommandString(aPs) === normaliseCommandString(bPs));
-}
-/**
- * Upsert method-managed events into an existing hook file. Adopter-
- * added events (no sentinel) survive. An unmarked adopter event that
- * is equivalent (modulo sentinel) to a method-managed event we're
- * adding gets de-duped — same safety net as the Claude Code merge
- * post-v0.12.2.
- */
-export function upsertCopilotHookFile(existing, owned) {
-    const currentEvents = existing?.events ?? [];
-    let dedupedAny = false;
-    const adopterEvents = currentEvents.filter((evt) => {
-        if (isMethodManagedEvent(evt))
-            return false;
-        const equivalent = owned.some((o) => eventsEquivalentExcludingSentinel(evt, o));
-        if (equivalent) {
-            dedupedAny = true;
-            return false;
-        }
-        return true;
-    });
-    const before = currentEvents.filter((e) => isMethodManagedEvent(e));
-    const after = owned;
-    const methodChanged = JSON.stringify(before) !== JSON.stringify(after);
-    const nextFile = {
-        version: 1,
-        events: [...adopterEvents, ...owned],
-    };
-    return {
-        file: nextFile,
-        changed: methodChanged || dedupedAny,
-    };
-}
-/**
- * Detect adopter drift: an event still carrying the sentinel but whose
- * content no longer matches the canonical version we'd write. Returns
- * `true` iff drift is present.
- */
-export function detectCopilotHookDrift(existing, owned) {
-    if (!existing)
-        return false;
-    const existingMethod = existing.events.filter((e) => isMethodManagedEvent(e));
-    if (existingMethod.length === 0)
-        return false;
-    return JSON.stringify(existingMethod) !== JSON.stringify(owned);
-}
-//# sourceMappingURL=copilot.js.map

package/dist/lib/hooks-seed/lifecycle-mapping.js

@@ -1,28 +0,0 @@
-/**
- * Portable lifecycle event class → harness-native event mapping per
- * ADR 0141 §4.3 and the table in `docs/method/foundations/lifecycle-event-classes.yaml`.
- *
- * Adding a new harness binding is mechanical: extend `AgentHarness`
- * in src/lib/agent-harness.ts and add a row here. Hook builders
- * consume this mapping rather than hand-coding native event names.
- */
-const MAPPINGS = {
-    "claude-code": {
-        pre_tool_use: "PreToolUse",
-        post_tool_use: "PostToolUse",
-        user_prompt_submit: "UserPromptSubmit",
-        session_start: "SessionStart",
-        session_stop: "Stop",
-    },
-    "github-copilot-cli": {
-        pre_tool_use: "preToolUse",
-        post_tool_use: "postToolUse",
-        user_prompt_submit: "userPromptSubmitted",
-        session_start: "sessionStart",
-        session_stop: "agentStop",
-    },
-};
-export function nativeEventName(harness, portable) {
-    return MAPPINGS[harness][portable];
-}
-//# sourceMappingURL=lifecycle-mapping.js.map

package/dist/lib/mcp-seed/entries.js

@@ -1,14 +0,0 @@
-/**
- * Entry builders — produce the McpServerEntry blocks this plan owns.
- */
-export function buildSddMcpEntry(opts = {}) {
-    const entry = {
-        command: "sdd-cli",
-        args: ["mcp", "serve"],
-        ...(opts.sddRepoPath !== undefined
-            ? { env: { SDD_REPO_PATH: opts.sddRepoPath } }
-            : {}),
-    };
-    return entry;
-}
-//# sourceMappingURL=entries.js.map

package/dist/lib/mcp-seed/index.js

@@ -1,28 +0,0 @@
-/**
- * Public facade for the MCP settings-seed library. Consumers:
- *
- *   - `sdd-cli init` scaffolds (platform/app/integration) call
- *     `buildMethodManagedServers()` + `upsertMethodManagedServers()`
- *     to produce a correctly-seeded `.claude/settings.json`.
- *   - `sdd-cli sync` routes the same file through the merge path to
- *     upsert method-owned entries without clobbering adopter content.
- *
- * Scope: this module owns `mcpServers.<method-id>`. Hooks and other
- * top-level keys belong to the enforcement-automation plan; we pass
- * them through untouched.
- */
-export { METHOD_MANAGED_SERVER_IDS } from "./types.js";
-export { buildSddMcpEntry } from "./entries.js";
-export { detectManagedDrift, upsertMethodManagedServers, } from "./merge.js";
-import { buildSddMcpEntry } from "./entries.js";
-/**
- * Produce the full owned-servers map. Adding a new method-managed
- * server id is a one-place change: add it here and to
- * METHOD_MANAGED_SERVER_IDS.
- */
-export function buildMethodManagedServers(opts = {}) {
-    return {
-        "sdd-mcp": buildSddMcpEntry(opts.sddRepoPath !== undefined ? { sddRepoPath: opts.sddRepoPath } : {}),
-    };
-}
-//# sourceMappingURL=index.js.map

package/dist/lib/mcp-seed/merge.js

@@ -1,99 +0,0 @@
-/**
- * Merge logic for the method-managed portion of `.claude/settings.json`.
- *
- * Ownership model: the method owns specific server ids (listed in
- * `METHOD_MANAGED_SERVER_IDS`). On upsert, those ids are rewritten
- * with the method-supplied entry; any other server ids the adopter
- * has added under `mcpServers` survive untouched, as do all other
- * top-level keys (hooks, permissions, env, …).
- *
- * The merge is conservative: if a method id exists with a value that
- * is byte-identical to the method's current seed, we return the
- * original object unmodified (stable output → no spurious writes).
- */
-export function upsertMethodManagedServers(existing, owned) {
-    const added = [];
-    const updated = [];
-    const unchanged = [];
-    const currentServers = isPlainObject(existing["mcpServers"])
-        ? existing["mcpServers"]
-        : {};
-    const nextServers = { ...currentServers };
-    for (const [id, entry] of Object.entries(owned)) {
-        const prior = currentServers[id];
-        if (prior === undefined) {
-            nextServers[id] = entry;
-            added.push(id);
-        }
-        else if (!entriesEqual(prior, entry)) {
-            nextServers[id] = entry;
-            updated.push(id);
-        }
-        else {
-            unchanged.push(id);
-        }
-    }
-    const changed = added.length > 0 || updated.length > 0;
-    if (!changed) {
-        return {
-            settings: existing,
-            added,
-            updated,
-            unchanged,
-            changed: false,
-        };
-    }
-    const nextSettings = {
-        ...existing,
-        mcpServers: nextServers,
-    };
-    return {
-        settings: nextSettings,
-        added,
-        updated,
-        unchanged,
-        changed: true,
-    };
-}
-/**
- * Detect adopter-edited method-managed entries. Returns the ids whose
- * current value differs from the method-supplied seed — these are the
- * ones that a refuse-or-overwrite sync should flag unless
- * `--allow-overwrite` is passed.
- */
-export function detectManagedDrift(existing, owned) {
-    const currentServers = isPlainObject(existing["mcpServers"])
-        ? existing["mcpServers"]
-        : {};
-    const drifted = [];
-    for (const [id, entry] of Object.entries(owned)) {
-        const prior = currentServers[id];
-        if (prior !== undefined && !entriesEqual(prior, entry)) {
-            drifted.push(id);
-        }
-    }
-    return drifted;
-}
-function entriesEqual(a, b) {
-    // Stable-order JSON comparison. The entry shape is small and flat
-    // enough that stringifying is cheaper than writing a structural
-    // walker.
-    return stableStringify(a) === stableStringify(b);
-}
-function stableStringify(value) {
-    if (value === null || typeof value !== "object")
-        return JSON.stringify(value);
-    if (Array.isArray(value)) {
-        return "[" + value.map((v) => stableStringify(v)).join(",") + "]";
-    }
-    const keys = Object.keys(value).sort();
-    return ("{" +
-        keys
-            .map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]))
-            .join(",") +
-        "}");
-}
-function isPlainObject(v) {
-    return v !== null && typeof v === "object" && !Array.isArray(v);
-}
-//# sourceMappingURL=merge.js.map

package/dist/lib/mcp-seed/types.js

@@ -1,13 +0,0 @@
-/**
- * Types for the MCP settings-seed library. Mirrors the shape Claude
- * Code expects at `.claude/settings.json`, restricted to the fields
- * we read or write.
- */
-/**
- * Server ids owned by this method plan. Sync upserts these and leaves
- * everything else alone. When Phases 3+4 ship adopter servers, extend
- * the list — or better, let each plan contribute its own list and
- * combine at merge time.
- */
-export const METHOD_MANAGED_SERVER_IDS = ["sdd-mcp"];
-//# sourceMappingURL=types.js.map

package/dist/lib/sync/copilot-hooks-merge.js

@@ -1,108 +0,0 @@
-/**
- * `.github/hooks/*.json` merge pass during `sdd-cli sync` when the
- * adopter opted into `--agent-harness github-copilot-cli`.
- *
- * Method-managed event entries are sentinel-tagged via their
- * `command.bash` / `command.powershell` strings. Adopter-added events
- * in the same `events[]` array survive sync. Drift inside a method-
- * managed event refuses without `--allow-overwrite`, symmetric to the
- * Claude Code settings-merge path.
- */
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { buildMethodManagedCopilotHooks, detectCopilotHookDrift, upsertCopilotHookFile, } from "../hooks-seed/copilot.js";
-export async function syncMethodManagedCopilotHooks(opts) {
-    const surface = buildMethodManagedCopilotHooks();
-    const entries = Object.entries(surface);
-    // First pass: detect drift across all files. If any drifted file
-    // would be refused (no --allow-overwrite), we refuse the whole
-    // merge without writing — same all-or-nothing posture as the
-    // Claude Code settings merge.
-    const reads = [];
-    for (const [portableClass, { filePath, events }] of entries) {
-        const absPath = join(opts.targetRepo, filePath);
-        const existing = await readHookFile(absPath);
-        const drifted = detectCopilotHookDrift(existing, events);
-        reads.push({
-            portableClass,
-            relPath: filePath,
-            absPath,
-            existing,
-            owned: events,
-            drifted,
-        });
-    }
-    const driftedFiles = reads.filter((r) => r.drifted).map((r) => r.relPath);
-    if (driftedFiles.length > 0 && !opts.allowOverwrite) {
-        return {
-            files: reads.map((r) => ({
-                relPath: r.relPath,
-                portableClass: r.portableClass,
-                drifted: r.drifted,
-                wrote: false,
-            })),
-            driftedRefused: driftedFiles,
-            refused: true,
-        };
-    }
-    if (opts.checkOnly) {
-        return {
-            files: reads.map((r) => ({
-                relPath: r.relPath,
-                portableClass: r.portableClass,
-                drifted: r.drifted,
-                wrote: false,
-            })),
-            driftedRefused: [],
-            refused: false,
-        };
-    }
-    // Second pass: upsert + write.
-    const fileResults = [];
-    for (const r of reads) {
-        const merge = upsertCopilotHookFile(r.existing, r.owned);
-        let wrote = false;
-        if (merge.changed || r.existing === null) {
-            await mkdir(dirname(r.absPath), { recursive: true });
-            await writeFile(r.absPath, JSON.stringify(merge.file, null, 2) + "\n", "utf8");
-            wrote = true;
-        }
-        fileResults.push({
-            relPath: r.relPath,
-            portableClass: r.portableClass,
-            drifted: r.drifted,
-            wrote,
-        });
-    }
-    return { files: fileResults, driftedRefused: [], refused: false };
-}
-async function readHookFile(absPath) {
-    if (!(await fileExists(absPath)))
-        return null;
-    const raw = await readFile(absPath, "utf8");
-    if (raw.trim().length === 0)
-        return null;
-    try {
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            const obj = parsed;
-            if (Array.isArray(obj["events"])) {
-                return obj;
-            }
-        }
-    }
-    catch {
-        /* fall through — treat malformed as empty so the next write reseats it */
-    }
-    return null;
-}
-async function fileExists(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-//# sourceMappingURL=copilot-hooks-merge.js.map