@sdd-method/author-cli 0.0.0-stage → 0.1.0

package/dist/lib/plan/render-template.js

@@ -0,0 +1,84 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Where a synced baseline carries the pilot-kickoff template: methods/templates/ since the method's
+ * methods/ subdivision, then the flat methods/ path older baselines still hold. Reading only the old
+ * path left `plan --pilot` failing in every SDD synced after the move.
+ */
+export const PILOT_TEMPLATE_REL_PATHS = [
+    "docs/method/methods/templates/pilot-kickoff-template.md",
+    "docs/method/methods/pilot-kickoff-template.md",
+];
+/** The first pilot-kickoff template present under the SDD root, or undefined. */
+export async function resolvePilotTemplate(sddRoot) {
+    for (const rel of PILOT_TEMPLATE_REL_PATHS) {
+        const p = join(sddRoot, rel);
+        try {
+            await access(p);
+            return p;
+        }
+        catch {
+            // try the next location
+        }
+    }
+    return undefined;
+}
+const VAR_PATTERN = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+export async function renderPilotKickoff(inputs) {
+    const { snapshot } = inputs;
+    const templatePath = await resolvePilotTemplate(snapshot.sddRoot);
+    if (templatePath === undefined)
+        throw new Error(`no pilot-kickoff template under ${snapshot.sddRoot}`);
+    const template = await readFile(templatePath, "utf8");
+    const vars = buildVars(inputs);
+    return template.replace(VAR_PATTERN, (match, name) => {
+        if (!(name in vars)) {
+            // Leave unknown placeholders intact so the human can see what wasn't
+            // prefilled and fill it themselves, rather than silently blanking.
+            return match;
+        }
+        return vars[name] ?? "";
+    });
+}
+function buildVars(inputs) {
+    const { snapshot, platformCliVersionHint, today } = inputs;
+    const { repoConfig } = snapshot;
+    const inlineList = (items, sep = ", ") => items.length === 0 ? "_(none declared — fill in)_" : items.join(sep);
+    const bulletList = (items) => items.length === 0 ? "- _(none declared — fill in)_" : items.map((i) => `- ${i}`).join("\n");
+    return {
+        service_name: snapshot.service,
+        capability: snapshot.capability,
+        capability_display: toTitleCase(snapshot.capability.replace(/-/g, " ")),
+        domain: snapshot.domain,
+        domain_display: toTitleCase(snapshot.domain),
+        service_type: repoConfig.serviceType ?? "_(not declared — fill in)_",
+        today,
+        platform_cli_version_hint: platformCliVersionHint,
+        capability_spec_path: snapshot.capabilitySpecPath,
+        capability_spec_present: snapshot.capabilitySpecPresent ? "present" : "**MISSING — author before kickoff**",
+        capability_spec_state: snapshot.capabilitySpecPresent
+            ? "Exists; run `/validate-intent-quality` before kickoff"
+            : "**MISSING** — author before kickoff",
+        traceability_manifest_path: snapshot.traceabilityManifestPath,
+        traceability_manifest_present: snapshot.traceabilityManifestPresent ? "present" : "**MISSING — author before kickoff**",
+        traceability_manifest_state: snapshot.traceabilityManifestPresent
+            ? "Exists; confirm `status:` before kickoff"
+            : "**MISSING** — author before kickoff",
+        feature_spec_count: String(snapshot.featureSpecCount),
+        feature_spec_paths_inline: inlineList(snapshot.featureSpecRelativePaths),
+        feature_spec_paths_list: bulletList(snapshot.featureSpecRelativePaths),
+        aggregate_count: String(repoConfig.aggregates.length),
+        aggregate_list_inline: inlineList(repoConfig.aggregates),
+        internal_dependencies_inline: repoConfig.internalDependencies.length === 0
+            ? "_(none — zero internal mocking required)_"
+            : repoConfig.internalDependencies.join(", "),
+        openapi_count: String(repoConfig.contracts.openapi.length),
+        proto_count: String(repoConfig.contracts.proto.length),
+        avro_count: String(repoConfig.contracts.avro.length),
+        spicedb_count: String(repoConfig.contracts.spicedb.length),
+    };
+}
+function toTitleCase(s) {
+    return s.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+//# sourceMappingURL=render-template.js.map

package/dist/lib/repo-kind.js

@@ -0,0 +1,129 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Forward-base bundles set `.sdd-repo-kind` and qualify as the base
+ * layer that additive extensions can compose on top of (per ADR 0135).
+ * The legacy self-contained `reverse-baseline` is retained as a
+ * forward base for compat with adopters who haven't migrated to the
+ * `reverse-extension-baseline` additive shape yet.
+ */
+const FORWARD_BASE_BUNDLES = new Set([
+    "platform-baseline",
+    "app-baseline",
+    "integration-baseline",
+    "reverse-baseline",
+]);
+export const REPO_KIND_FILE = ".sdd-repo-kind";
+/**
+ * Legacy marker filename from the pre-rebrand era. Read-only fallback during
+ * the rebrand transition: `readRepoKind` accepts either filename; `sync`
+ * auto-migrates legacy → canonical. New writes always use `REPO_KIND_FILE`.
+ * Drop after one minor-version overlap.
+ */
+export const LEGACY_REPO_KIND_FILE = ".iteraitive-repo-kind";
+const PROFILE_BY_REPO_KIND = {
+    "platform-product": "platform",
+    "application-product": "application",
+    "integration-product": "integration",
+    "reverse-corpus": "reverse",
+};
+const REPO_KIND_BY_PROFILE = {
+    platform: "platform-product",
+    application: "application-product",
+    integration: "integration-product",
+    reverse: "reverse-corpus",
+};
+/**
+ * Forward-base bundles map 1:1 to a profile. Additive bundles
+ * (`reverse-extension-baseline`) have no profile of their own — they
+ * compose on top of whatever forward base is already locked.
+ */
+const PROFILE_BY_BUNDLE_NAME = {
+    "platform-baseline": "platform",
+    "app-baseline": "application",
+    "integration-baseline": "integration",
+    "reverse-baseline": "reverse",
+};
+const BUNDLE_NAME_BY_PROFILE = {
+    platform: "platform-baseline",
+    application: "app-baseline",
+    integration: "integration-baseline",
+    reverse: "reverse-baseline",
+};
+export function profileFromRepoKind(kind) {
+    return PROFILE_BY_REPO_KIND[kind];
+}
+export function repoKindFromProfile(profile) {
+    return REPO_KIND_BY_PROFILE[profile];
+}
+/**
+ * Returns the profile a bundle authoritatively claims, or null for
+ * additive bundles that don't claim a profile of their own. Accepts
+ * arbitrary strings (adopter pack names per ADR 0151) and returns null
+ * for any name not in the closed sdd-method bundle set.
+ */
+export function profileFromBundleName(name) {
+    if (!isBundleName(name))
+        return null;
+    return PROFILE_BY_BUNDLE_NAME[name] ?? null;
+}
+export function bundleNameFromProfile(profile) {
+    return BUNDLE_NAME_BY_PROFILE[profile];
+}
+/**
+ * Forward-base bundles set `.sdd-repo-kind` and qualify as the base
+ * layer that additive extensions compose on top of. Additive bundles
+ * (sdd-method's `reverse-extension-baseline` and ADR 0151 adopter
+ * packs) return false. Accepts arbitrary strings; unknown names return
+ * false.
+ */
+export function isForwardBase(name) {
+    if (!isBundleName(name))
+        return false;
+    return FORWARD_BASE_BUNDLES.has(name);
+}
+/**
+ * Maps repo-kind → forward-base bundle name. Used when migrating a
+ * legacy v1 lock file (which doesn't record bundle name) to v2.
+ */
+export function bundleNameFromRepoKind(kind) {
+    return BUNDLE_NAME_BY_PROFILE[PROFILE_BY_REPO_KIND[kind]];
+}
+export function isRepoKind(value) {
+    return value in PROFILE_BY_REPO_KIND;
+}
+const ALL_BUNDLE_NAMES = new Set([
+    "platform-baseline",
+    "app-baseline",
+    "integration-baseline",
+    "reverse-baseline",
+    "reverse-extension-baseline",
+]);
+export function isBundleName(value) {
+    return ALL_BUNDLE_NAMES.has(value);
+}
+export async function readRepoKind(repoRoot) {
+    // Canonical first; fall back to legacy marker during the rebrand transition.
+    for (const filename of [REPO_KIND_FILE, LEGACY_REPO_KIND_FILE]) {
+        const path = join(repoRoot, filename);
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+        const value = raw.trim();
+        if (!isRepoKind(value)) {
+            throw new Error(`Unrecognised ${filename} value: ${JSON.stringify(value)} at ${path}`);
+        }
+        return value;
+    }
+    return null;
+}
+export async function writeRepoKind(repoRoot, kind) {
+    await writeFile(join(repoRoot, REPO_KIND_FILE), `${kind}\n`, "utf8");
+}
+//# sourceMappingURL=repo-kind.js.map

package/dist/lib/scaffold/domain.js

@@ -0,0 +1,234 @@
+import { access, copyFile, mkdir, readdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+/**
+ * Domain scaffolding (ADR 0173). Writes the invariant domain shape into a
+ * platform-root SDD, optionally seeded from a domain archetype. The generic
+ * shape is method-owned and domain-agnostic; archetypes overlay starter content.
+ *
+ * Only the `integration` archetype is built in (the method tier — the method
+ * owns that vocabulary via ADR 0171/0172). Reference-architecture and adopter
+ * archetypes are resolved from a consumed registry (not in this prototype).
+ */
+export const METHOD_DOMAIN_ARCHETYPES = ["integration"];
+export function isMethodDomainArchetype(value) {
+    return METHOD_DOMAIN_ARCHETYPES.includes(value);
+}
+export async function scaffoldDomain(input) {
+    const base = join(input.targetRepo, "docs", "domains", input.name);
+    const filesWritten = [];
+    const write = async (rel, content) => {
+        await writeFileAt(join(base, rel), content);
+        filesWritten.push(join("docs", "domains", input.name, rel));
+    };
+    const writeIfMissing = async (rel, content) => {
+        if (await fileExists(join(base, rel)))
+            return;
+        await write(rel, content);
+    };
+    // Registry archetype (ADR 0176 §4.4): copy seed files from the bundle
+    // cache FIRST — copy-and-own; the generic shape then fills only the
+    // gaps the seed didn't provide.
+    if (input.registryArchetype) {
+        const copied = await copyRegistrySeeds(input.registryArchetype, base);
+        for (const rel of copied) {
+            filesWritten.push(join("docs", "domains", input.name, rel));
+        }
+    }
+    await writeIfMissing("README.md", renderDomainReadme(input));
+    await writeIfMissing("architecture/glossary.md", renderDomainGlossary(input));
+    await writeIfMissing("architecture/data-model.mermaid.md", renderDomainDataModel(input));
+    await writeIfMissing("architecture/diagrams/.gitkeep", "");
+    await writeIfMissing("architecture/adr/.gitkeep", "");
+    await writeIfMissing("design/.gitkeep", "");
+    await writeIfMissing("product/.gitkeep", "");
+    if (input.withContracts) {
+        await writeIfMissing("contracts/.gitkeep", "");
+    }
+    // Archetype overlay (method tier).
+    if (input.archetype === "integration") {
+        await write("architecture/interaction-patterns.md", renderIntegrationArchetype());
+    }
+    return { filesWritten };
+}
+/**
+ * Copy a registry archetype's seed files from the bundle cache into the
+ * domain directory, stripping the seed prefix: a seed prefix
+ * `core-b2b-saas/domains/identity/` maps its files onto the domain root.
+ * Returns the relative paths written (relative to the domain dir).
+ */
+async function copyRegistrySeeds(archetype, domainDir) {
+    const written = [];
+    for (const seedPrefix of archetype.seeds) {
+        const seedRoot = join(archetype.bundleCacheDir, seedPrefix);
+        const files = await walkFiles(seedRoot);
+        for (const abs of files) {
+            const rel = relative(seedRoot, abs);
+            const dst = join(domainDir, rel);
+            await mkdir(dirname(dst), { recursive: true });
+            await copyFile(abs, dst);
+            written.push(rel);
+        }
+    }
+    if (written.length === 0) {
+        throw new Error(`Archetype '${archetype.id}' (bundle ${archetype.bundleName}) has no seed files in the cache — re-sync the bundle.`);
+    }
+    return written;
+}
+async function walkFiles(root) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const child = join(root, e.name);
+        if (e.isDirectory()) {
+            out.push(...(await walkFiles(child)));
+        }
+        else if (e.isFile()) {
+            out.push(child);
+        }
+    }
+    return out;
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function titleize(slug) {
+    return slug
+        .split("-")
+        .filter((p) => p.length > 0)
+        .map((p) => p[0].toUpperCase() + p.slice(1))
+        .join(" ");
+}
+function renderDomainReadme(input) {
+    const title = titleize(input.name);
+    const intro = input.archetype === "integration"
+        ? "Provider-specific integrations that bridge external systems to the platform via canonical contracts. Each integration is a separate `integration-product` SDD that registers into this domain (ADR 0136)."
+        : `TODO: one-paragraph description of the ${title} domain — the capability slice it owns and its boundary.`;
+    return ([
+        `# ${title} Domain`,
+        "",
+        `> ${intro}`,
+        "",
+        "## Architecture",
+        "",
+        "- [Glossary](architecture/glossary.md) — domain vocabulary",
+        "- [Data Model](architecture/data-model.mermaid.md) — entity-relationship diagram",
+        "- [ADRs](architecture/adr/) — domain-specific architecture decisions",
+        "- [Diagrams](architecture/diagrams/) — C4 and other diagrams",
+        ...(input.archetype === "integration"
+            ? [
+                "- [Interaction Patterns](architecture/interaction-patterns.md) — ingestion / invocation patterns (sdd-method#0171/#0172)",
+            ]
+            : []),
+        "",
+        "## Product",
+        "",
+        "- [Capability Specs](product/) — domain capabilities",
+        "",
+        "## Design",
+        "",
+        "- [Design](design/) — feature/design grounding",
+        ...(input.withContracts
+            ? ["", "## Contracts", "", "- [Contracts](contracts/) — contracts this domain exposes"]
+            : []),
+        "",
+    ].join("\n"));
+}
+function renderDomainGlossary(input) {
+    const title = titleize(input.name);
+    if (input.archetype === "integration") {
+        return ([
+            `# ${title} Domain Glossary`,
+            "",
+            "> Vocabulary for this domain. Interaction-pattern terms below are anchored in",
+            "> Enterprise Integration Patterns (sdd-method#0172).",
+            "",
+            "| Term | Definition |",
+            "|------|------------|",
+            "| Provider | An external system this platform integrates with. |",
+            "| Ingestion pattern | How an integration acquires data (event-stream-consume / webhook / socket-listen / poll). |",
+            "| Invocation pattern | How an integration invokes a provider (request-response / async-request / publish). |",
+            "| CanonicalEvent | The normalised event an integration translates provider data into. |",
+            "",
+        ].join("\n"));
+    }
+    return ([
+        `# ${title} Domain Glossary`,
+        "",
+        "> Owned vocabulary for this domain. One row per term the domain defines.",
+        "",
+        "| Term | Definition |",
+        "|------|------------|",
+        "| TODO | TODO — define the domain's core terms. |",
+        "",
+    ].join("\n"));
+}
+function renderDomainDataModel(input) {
+    const title = titleize(input.name);
+    return ([
+        `# ${title} Domain — Data Model`,
+        "",
+        "> Entity-relationship diagram for this domain (ADR 0142 — first-class catalogue entity).",
+        "",
+        "```mermaid",
+        "erDiagram",
+        "    %% TODO: model this domain's entities and relationships",
+        "    ENTITY {",
+        "        string id",
+        "    }",
+        "```",
+        "",
+    ].join("\n"));
+}
+function renderIntegrationArchetype() {
+    return ([
+        "# Integration Interaction Patterns",
+        "",
+        "> Seeded by the `integration` domain archetype (sdd-method#0173). The interaction",
+        "> pattern is the adopter-agnostic, EIP-anchored data-flow axis (sdd-method#0171),",
+        "> orthogonal to provider category (`profileType`, sdd-method#0137).",
+        "",
+        "## Ingestion (inbound)",
+        "",
+        "| Pattern | Meaning |",
+        "|---------|---------|",
+        "| `event-stream-consume` | Subscribe to / drain a provider-hosted broker, stream or feed. |",
+        "| `webhook` | Expose an endpoint the provider pushes events to. |",
+        "| `socket-listen` | Accept connection-oriented sessions and read framed data. |",
+        "| `poll` | Request the provider on a schedule. |",
+        "",
+        "## Invocation (outbound)",
+        "",
+        "| Pattern | Meaning |",
+        "|---------|---------|",
+        "| `request-response` | Synchronous call-and-wait. |",
+        "| `async-request` | Submit; result returns later via a separate channel, correlated. |",
+        "| `publish` | Fire-and-forget write to a broker. |",
+        "",
+        "## Adopter framework roles",
+        "",
+        "If your platform runs an integration/component framework, map its component roles",
+        "onto these patterns **here** (sdd-method#0171 §9.5) — the method stays role-name-neutral.",
+        "",
+        "| Your role | Ingestion / Invocation pattern |",
+        "|-----------|-------------------------------|",
+        "| TODO | TODO |",
+        "",
+    ].join("\n"));
+}
+async function writeFileAt(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+}
+//# sourceMappingURL=domain.js.map

package/dist/lib/scaffold/registry.js

@@ -0,0 +1,136 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { BUNDLE_CACHE_REL, REGISTRY_FILE } from "../sync/bundle-cache.js";
+/**
+ * Scan the bundle cache for registries and return every archetype found.
+ * Bundles without any registry.yaml are skipped silently (vendor packs
+ * etc.). A registry may sit at the bundle's payload root or nested
+ * (multi-bundle producer repos keep one registry per bundle subtree,
+ * e.g. a vertical overlay's `verticals/fleet/registry.yaml`) — all are
+ * read; seed paths stay payload-root-relative regardless of where the
+ * declaring registry sits.
+ */
+export async function discoverArchetypes(targetRepo) {
+    const cacheRoot = join(targetRepo, BUNDLE_CACHE_REL);
+    let entries;
+    try {
+        entries = await readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const bundleCacheDir = join(cacheRoot, e.name);
+        const at = e.name.lastIndexOf("@");
+        const bundleName = at > 0 ? e.name.slice(0, at) : e.name;
+        for (const registryPath of await findRegistryFiles(bundleCacheDir)) {
+            let raw;
+            try {
+                raw = await readFile(registryPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = parseYaml(raw);
+            }
+            catch {
+                continue; // malformed registry — skip rather than break scaffold
+            }
+            if (parsed === null || typeof parsed !== "object")
+                continue;
+            if (!Array.isArray(parsed.archetypes))
+                continue;
+            const tier = typeof parsed.tier === "string" ? parsed.tier : "unknown";
+            for (const a of parsed.archetypes) {
+                if (a === null || typeof a !== "object")
+                    continue;
+                const rec = a;
+                const id = typeof rec.id === "string" ? rec.id : undefined;
+                const seeds = Array.isArray(rec.seeds)
+                    ? rec.seeds.filter((s) => typeof s === "string")
+                    : [];
+                if (!id || seeds.length === 0)
+                    continue;
+                out.push({
+                    id,
+                    tier,
+                    seeds,
+                    bundleName,
+                    bundleCacheDir,
+                    ...(typeof rec.layer === "string" && { layer: rec.layer }),
+                    ...(typeof rec.domain_name === "string" && { domainName: rec.domain_name }),
+                    ...(typeof rec.status === "string" && { status: rec.status }),
+                    ...(typeof rec.notes === "string" && { notes: rec.notes }),
+                });
+            }
+        }
+    }
+    return out;
+}
+/** Depth cap for nested-registry discovery — bundle payloads are shallow. */
+const REGISTRY_SCAN_MAX_DEPTH = 4;
+/**
+ * Find every registry.yaml within a cached bundle (root + nested),
+ * depth-capped. Returns absolute paths in a stable (sorted) order.
+ */
+async function findRegistryFiles(dir, depth = 0) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.isFile() && e.name === REGISTRY_FILE) {
+            found.push(join(dir, e.name));
+        }
+        else if (e.isDirectory() && depth < REGISTRY_SCAN_MAX_DEPTH) {
+            found.push(...(await findRegistryFiles(join(dir, e.name), depth + 1)));
+        }
+    }
+    return found;
+}
+/**
+ * Resolve an archetype reference against the cache. Accepts bare ids
+ * (`core/identity`) and bundle-qualified ids
+ * (`ref-arch-core-b2b-saas:core/identity`).
+ */
+export async function resolveArchetype(targetRepo, reference) {
+    const available = await discoverArchetypes(targetRepo);
+    let bundleFilter;
+    let id = reference;
+    const colon = reference.indexOf(":");
+    if (colon > 0) {
+        bundleFilter = reference.slice(0, colon);
+        id = reference.slice(colon + 1);
+    }
+    const matches = available.filter((a) => a.id === id && (bundleFilter === undefined || a.bundleName === bundleFilter));
+    if (matches.length === 1) {
+        return { ok: true, archetype: matches[0], available };
+    }
+    if (matches.length === 0) {
+        const known = available.map((a) => `${a.bundleName}:${a.id}`).join(", ");
+        return {
+            ok: false,
+            available,
+            error: available.length === 0
+                ? `No archetype registries found in ${BUNDLE_CACHE_REL}/ — sync an archetype-bearing bundle first (ADR 0176).`
+                : `Archetype '${reference}' not found in cached registries. Available: ${known}`,
+        };
+    }
+    const collisions = matches.map((a) => `${a.bundleName}:${a.id}`).join(", ");
+    return {
+        ok: false,
+        available,
+        error: `Archetype id '${id}' is declared by multiple bundles (${collisions}). Use the qualified form '<bundle>:<id>'.`,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/lib/scripts.js

@@ -0,0 +1,7 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolveBundledScript(name) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "..", "..", "scripts", name);
+}
+//# sourceMappingURL=scripts.js.map