@selvakumaresra/specship 0.1.3 → 0.3.0

package/dist/workflows/condition-evaluator.js

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Condition evaluator + `$nodeId.output` substitution.
+ *
+ * Modeled on Archon's evaluator (packages/workflows/src/dag-executor.ts:331-372).
+ *
+ * Two responsibilities:
+ *   1. Substitute `$nodeId.output[.field]` references in a template string
+ *      with the corresponding upstream node output.
+ *   2. Evaluate `when:` expressions to gate a node's execution.
+ *
+ * Design choices:
+ *   - Unresolvable field references THROW `OutputRefError` (no silent drop).
+ *   - Unparseable `when:` expressions FAIL CLOSED (skip the node) so an
+ *     authoring mistake doesn't run a step the author didn't intend.
+ *   - Large outputs (>10KB) are spilled to a file and the substitution
+ *     emits a `$(cat <file>)` shell command for bash nodes (so they don't
+ *     blow up the shell argv); for prompt nodes the raw text is inlined.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputRefError = void 0;
+exports.substituteRefs = substituteRefs;
+exports.evaluateCondition = evaluateCondition;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class OutputRefError extends Error {
+    ref;
+    constructor(ref, message) {
+        super(`OutputRef "${ref}": ${message}`);
+        this.ref = ref;
+        this.name = 'OutputRefError';
+    }
+}
+exports.OutputRefError = OutputRefError;
+/** Pattern matching `$nodeId` or `$nodeId.output` or `$nodeId.output.field` or `$VAR`. */
+const REF_PATTERN = /\$([A-Z_][A-Z0-9_]*|[a-zA-Z_][a-zA-Z0-9_-]*)(?:\.([a-zA-Z_][a-zA-Z0-9_]*))?(?:\.([a-zA-Z_][a-zA-Z0-9_]*))?/g;
+const DEFAULT_SPILL_THRESHOLD = 10 * 1024;
+/**
+ * Substitute references in a template. Returns the substituted string.
+ * Throws OutputRefError for unresolvable named-field references.
+ *
+ * `forBash`: when true and a substituted value exceeds the spill threshold,
+ * writes the value to a temp file and substitutes `$(cat <file>)` instead
+ * of the raw text — preventing shell argv overflow.
+ */
+function substituteRefs(template, ctx, opts = {}) {
+    const spillDir = ctx.spillDir ?? require('os').tmpdir();
+    const threshold = ctx.spillThreshold ?? DEFAULT_SPILL_THRESHOLD;
+    return template.replace(REF_PATTERN, (match, name, second, third) => {
+        // Static variables ($CONTEXT, $ARTIFACTS_DIR, $INPUT.NAME): UPPER_SNAKE name.
+        if (/^[A-Z_][A-Z0-9_]*$/.test(name)) {
+            // `$INPUT.SPEC_ID` style: name='INPUT', second='SPEC_ID'
+            if (name === 'INPUT' && second) {
+                const v = ctx.inputs?.[second];
+                if (v === undefined) {
+                    throw new OutputRefError(match, `input "${second}" not provided to this workflow`);
+                }
+                return v;
+            }
+            // `$ARTIFACTS_DIR`, `$CONTEXT`, etc.
+            const v = ctx.variables?.[name];
+            if (v !== undefined)
+                return v;
+            // Fall through to node-id lookup (an UPPER_SNAKE word might be a node ID).
+        }
+        // Node-output reference. Second segment must be `output` for v1.
+        if (second !== 'output') {
+            // Bare `$nodeId` with no `.output` is treated as plain text (no substitution).
+            // This lets prompt authors include literal `$variableName` references
+            // without escaping when they're not addressing a node.
+            if (second === undefined)
+                return match;
+            throw new OutputRefError(match, `expected ".output" after node ID; got ".${second}"`);
+        }
+        const out = ctx.outputs.get(name);
+        if (!out) {
+            throw new OutputRefError(match, `node "${name}" has not produced output yet (not run, skipped, or failed)`);
+        }
+        let value;
+        if (third) {
+            // Field access: prefer structured, fall back to JSON-parsed text.
+            if (out.structured !== undefined && third in out.structured) {
+                value = out.structured[third];
+            }
+            else {
+                try {
+                    const parsed = JSON.parse(out.text);
+                    if (parsed && typeof parsed === 'object' && third in parsed) {
+                        value = parsed[third];
+                    }
+                    else {
+                        throw new OutputRefError(match, `field "${third}" not found in node "${name}" output`);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof OutputRefError)
+                        throw err;
+                    throw new OutputRefError(match, `node "${name}" output is not JSON-parseable; can't access field "${third}"`);
+                }
+            }
+        }
+        else {
+            value = out.text;
+        }
+        const asString = typeof value === 'string' ? value : JSON.stringify(value);
+        // Spill very large values to a file for bash nodes (argv overflow).
+        if (opts.forBash && asString.length > threshold) {
+            const filename = `cg-spill-${opts.nodeId ?? 'node'}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`;
+            const spillPath = path.join(spillDir, filename);
+            try {
+                fs.writeFileSync(spillPath, asString);
+                return `"$(cat ${shellEscape(spillPath)})"`;
+            }
+            catch {
+                // Fall through to inline if we can't spill — better than failing.
+            }
+        }
+        if (opts.forBash) {
+            // Single-quote-wrap for shell safety. Embedded single quotes get escaped.
+            return shellSingleQuote(asString);
+        }
+        return asString;
+    });
+}
+/**
+ * Evaluate a `when:` condition expression. Fail-closed: on parse error,
+ * returns false (the node skips).
+ *
+ * Grammar (subset, no parens):
+ *   expr   := and (`||` and)*
+ *   and    := cmp (`&&` cmp)*
+ *   cmp    := value op value
+ *   op     := `==` | `!=` | `<` | `>` | `<=` | `>=`
+ *   value  := $ref | 'string' | "string" | bare_word | number
+ */
+function evaluateCondition(expression, ctx) {
+    // First substitute $refs to their values (using a "raw" form — no quoting,
+    // no spilling). We do this before tokenizing so the parser sees literal
+    // values, not symbolic refs.
+    let substituted;
+    try {
+        substituted = substituteRefs(expression, ctx, { forBash: false });
+    }
+    catch (err) {
+        if (err instanceof OutputRefError) {
+            // Unresolvable ref in a `when:` expression — fail closed.
+            return false;
+        }
+        throw err;
+    }
+    try {
+        return evalOr(substituted);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Mini expression evaluator (no recursion through full grammar — linear scan).
+// ---------------------------------------------------------------------------
+function evalOr(expr) {
+    return splitTopLevel(expr, '||').some((sub) => evalAnd(sub.trim()));
+}
+function evalAnd(expr) {
+    return splitTopLevel(expr, '&&').every((sub) => evalCmp(sub.trim()));
+}
+function splitTopLevel(expr, sep) {
+    const out = [];
+    let depth = 0;
+    let last = 0;
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i <= expr.length - sep.length; i++) {
+        const ch = expr[i];
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        if (inSingle || inDouble)
+            continue;
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        if (depth === 0 && expr.startsWith(sep, i)) {
+            out.push(expr.slice(last, i));
+            last = i + sep.length;
+            i += sep.length - 1;
+        }
+    }
+    out.push(expr.slice(last));
+    return out;
+}
+const OP_PATTERN = /(==|!=|<=|>=|<|>)/;
+function evalCmp(expr) {
+    const trimmed = expr.trim();
+    if (trimmed === 'true')
+        return true;
+    if (trimmed === 'false')
+        return false;
+    const match = trimmed.match(OP_PATTERN);
+    if (!match) {
+        // No operator — treat as truthy test: non-empty string is true.
+        return parseValue(trimmed).trim().length > 0;
+    }
+    const op = match[1];
+    const idx = match.index;
+    const left = parseValue(trimmed.slice(0, idx).trim());
+    const right = parseValue(trimmed.slice(idx + op.length).trim());
+    if (op === '==')
+        return left === right;
+    if (op === '!=')
+        return left !== right;
+    // Numeric comparisons require both sides to be parseable as numbers.
+    const ln = Number(left);
+    const rn = Number(right);
+    if (!Number.isFinite(ln) || !Number.isFinite(rn))
+        return false;
+    switch (op) {
+        case '<': return ln < rn;
+        case '>': return ln > rn;
+        case '<=': return ln <= rn;
+        case '>=': return ln >= rn;
+    }
+    return false;
+}
+function parseValue(s) {
+    if (s.length >= 2) {
+        const first = s[0];
+        const last = s[s.length - 1];
+        if ((first === "'" && last === "'") || (first === '"' && last === '"')) {
+            return s.slice(1, -1);
+        }
+    }
+    return s;
+}
+// ---------------------------------------------------------------------------
+// Shell escaping helpers
+// ---------------------------------------------------------------------------
+function shellSingleQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function shellEscape(s) {
+    // Escape spaces and shell metachars for the `cat` argument.
+    if (/^[A-Za-z0-9_./@:+-]+$/.test(s))
+        return s;
+    return shellSingleQuote(s);
+}
+//# sourceMappingURL=condition-evaluator.js.map

package/dist/workflows/condition-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition-evaluator.js","sourceRoot":"","sources":["../../src/workflows/condition-evaluator.ts"],"names":[],"mappings":"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"}

package/dist/workflows/defaults/claude-design-implement.yaml

@@ -0,0 +1,247 @@
+name: claude-design-implement
+description: Import a Claude Design file (snapshot + tokens + source record), draft the spec, gate at review, write the spec — ready to hand off to /ss-implement.
+tags: [spec, ui, claude-design, default]
+requires: [specship, git]
+
+# Worktree isolation: the spec draft and snapshot live in the user's
+# working tree (not the worktree) so the artifacts survive the run,
+# but the worktree gives the spec author a clean diff to review and
+# means a rejected run leaves no half-written specs/<slug>.md.
+worktree:
+  enabled: true
+
+inputs:
+  - name: CONNECTOR_URL
+    description: The full Claude Design URL (https://claude.ai/design/p/<id>/?file=<name>.html)
+    required: true
+  - name: FILE_LABEL
+    description: Human label for the imported file (e.g. "Data Flow")
+    required: true
+  - name: SLUG
+    description: Kebab-case directory name under specs/ (e.g. "data-flow")
+    required: true
+  - name: OWNER
+    description: Spec owner — used in frontmatter when set
+    required: false
+  - name: PRIORITY
+    description: high / medium / low — used in frontmatter when set
+    required: false
+
+systemPromptAppend: |
+  You are implementing a Claude Design import for SpecShip.
+
+  The fidelity principle: never paraphrase or summarise design content
+  when capturing it. The snapshot HTML and tokens.css are the
+  zero-loss reference layer; the spec captures contract only (behaviour,
+  accessibility, responsive, interaction states, data shape).
+
+  Use whichever Claude Design tooling is available (an MCP connector,
+  the figma-implement-design skill, or a direct fetch) to pull the
+  source file. Save it byte-for-byte to specs/$INPUT.SLUG/snapshot.html.
+  Never edit the snapshot during this workflow.
+
+nodes:
+  - id: snapshot
+    kind: prompt
+    output_type: snapshot_summary
+    allowed_tools:
+      - Read
+      - Write
+      - Bash
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_search
+    prompt: |
+      Source URL:  $INPUT.CONNECTOR_URL
+      File label:  $INPUT.FILE_LABEL
+      Slug:        $INPUT.SLUG
+
+      Goal: snapshot the Claude Design source into specs/$INPUT.SLUG/
+      so the rest of the workflow has a zero-loss reference layer.
+
+      1. Create the directory `specs/$INPUT.SLUG/` if it doesn't exist.
+
+      2. Fetch the design content from $INPUT.CONNECTOR_URL. Try in
+         this order:
+           a. Any Claude Design MCP connector tool available in this
+              session (look for `mcp__*design*` or similar).
+           b. The `figma-implement-design` or `figma-use` skill if
+              loaded — Claude Design and Figma share a similar handoff
+              shape.
+           c. A direct `curl` of the URL, as a last resort.
+
+         Save the FULL rendered HTML byte-for-byte to
+         `specs/$INPUT.SLUG/snapshot.html`. Do NOT filter, summarise, or
+         re-format. If the design has linked CSS / asset files, save
+         them alongside.
+
+      3. Write `specs/$INPUT.SLUG/source.md` with the import audit
+         record:
+
+         ```markdown
+         # $INPUT.FILE_LABEL — Claude Design import
+
+         **Imported:** <today's date in YYYY-MM-DD>
+         **Connector URL:** $INPUT.CONNECTOR_URL
+         **Project ID:** <extracted from the URL — the segment after /p/>
+         **File:** $INPUT.FILE_LABEL
+
+         **Snapshot:** snapshot.html (byte-for-byte capture)
+         **Tokens:** tokens.css (extracted CSS custom properties)
+
+         **Original prompt:**
+         > Import this Claude Design project using the Claude Design connector:
+         > $INPUT.CONNECTOR_URL
+         > Implement: $INPUT.FILE_LABEL
+         ```
+
+      4. Extract CSS custom properties + literal token-like values
+         (colors, spacing, font sizes, radii, transitions) from the
+         snapshot to `specs/$INPUT.SLUG/tokens.css`. Use
+         `specship_explore` first to find the project's existing token
+         system — if a value in the snapshot matches an existing
+         project token, map it by name instead of duplicating.
+
+      Output: a ≤250-word summary covering:
+        - Snapshot structure (top-level layout, key components).
+        - Token mapping (which match existing project tokens, which are
+          new and added to tokens.css).
+        - Any visible interaction or state cues in the CSS (`:hover`,
+          `:focus`, `:disabled`, `[aria-*]` selectors) the spec
+          author should be aware of.
+
+  - id: draft_spec
+    kind: prompt
+    depends_on: [snapshot]
+    output_type: spec_markdown
+    allowed_tools:
+      - Read
+      - mcp__specship__specship_explore
+      - mcp__specship__specship_search
+      - mcp__specship__specship_node
+      - mcp__specship__specship_spec
+    prompt: |
+      Use the spec-author skill (~/.claude/skills/spec-author/SKILL.md
+      and its references/) to draft a SpecShip-compatible spec for the
+      Claude Design import. Inputs available on disk:
+
+        - specs/$INPUT.SLUG/snapshot.html  (visual + structural source)
+        - specs/$INPUT.SLUG/tokens.css     (design tokens)
+        - specs/$INPUT.SLUG/source.md      (audit record)
+
+      Spec scope: $INPUT.FILE_LABEL component(s).
+      Optional inputs: owner=$INPUT.OWNER  priority=$INPUT.PRIORITY
+
+      Cover, as separate REQs:
+        - Behavioural contract (what the component renders, given what data).
+        - Each visible state (default, hover, focused, pressed, disabled,
+          loading, error, empty) — derive from the CSS, gap-fill the rest.
+        - Accessibility (keyboard nav, ARIA roles, focus order, contrast,
+          screen-reader behaviour).
+        - Responsive behaviour (breakpoints by name, not pixels).
+        - Data shape + failure-mode contracts.
+        - Performance contract (initial render budget, interaction
+          latency, if applicable).
+
+      DO NOT put exact hex colors, pixel values, font names, or animation
+      durations in the spec. Reference design tokens by name
+      (`MUST use the --error color token`). The values themselves live
+      in tokens.css.
+
+      Embed the import-source record in the spec's frontmatter so the
+      spec carries its provenance:
+
+      ```yaml
+      ---
+      id: <SLUG-DOC>
+      title: <FILE_LABEL>
+      owner: <OWNER or "[needs review]">
+      priority: <PRIORITY or "[needs review]">
+      source: specs/<SLUG>/source.md
+      snapshot: specs/<SLUG>/snapshot.html
+      tokens: specs/<SLUG>/tokens.css
+      ---
+      ```
+
+      Output: the full Markdown body of the proposed spec
+      (with frontmatter, embedded `<!-- id: -->` markers, RFC 2119
+      keywords, acceptance bullets with .A1/.A2 IDs). DO NOT write
+      it to disk yet — the next node is a review gate.
+
+  - id: gap_review
+    kind: approval
+    depends_on: [draft_spec]
+    message: |
+      Spec draft ready for $INPUT.FILE_LABEL.
+
+      Walk the [needs review] markers and gap-fill questions, then
+      approve to write the file. Reject with feedback to revise.
+
+      ─────── DRAFT ───────
+      $draft_spec.output
+    capture_response: true
+    on_reject:
+      prompt: |
+        The draft was rejected with this feedback. Revise the spec
+        per the feedback; keep ALL existing REQ IDs stable so any
+        downstream tracking survives the rewrite.
+
+        Feedback:
+        $gap_review.output
+
+        Current draft:
+        $draft_spec.output
+
+        Output the revised draft.
+      max_attempts: 3
+
+  - id: write_spec
+    kind: prompt
+    depends_on: [gap_review]
+    output_type: file_path
+    allowed_tools:
+      - Write
+      - Read
+      - Bash
+    prompt: |
+      Write the approved spec to `specs/$INPUT.SLUG.md` using the
+      Write tool.
+
+      If `specs/$INPUT.SLUG.md` already exists (re-importing an
+      iteration), APPEND the new requirements to it instead of
+      overwriting; preserve all existing REQ IDs. Tell the user
+      explicitly what you did.
+
+      Approved draft:
+      $gap_review.output
+
+      Then run:
+        specship sync
+
+      Output: the relative path of the file written + the first REQ
+      ID (e.g. "REQ-DATA-FLOW-001") so the next step can hand it to
+      /ss-implement.
+
+  - id: handoff
+    kind: prompt
+    depends_on: [write_spec]
+    output_type: handoff_message
+    allowed_tools:
+      - Read
+    prompt: |
+      The spec is now indexed. Output a short hand-off message for the
+      user with EXACTLY these elements:
+
+        1. The path of the spec file: `specs/$INPUT.SLUG.md`.
+        2. The full list of REQ IDs the spec defines, one per line.
+        3. The reference files the implementation phase should read:
+             - specs/$INPUT.SLUG/snapshot.html
+             - specs/$INPUT.SLUG/tokens.css
+             - specs/$INPUT.SLUG/source.md
+        4. The exact next command:
+             /ss-implement <first REQ ID>
+        5. A one-line reminder that the implementation step should
+           load the snapshot for visual fidelity — the spec covers
+           contract only.
+
+      Keep the message ≤200 words. The user is about to switch from
+      this workflow to the implement workflow; this is the bridge.

package/dist/workflows/defaults/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Bundled default workflows.
+ *
+ * Workflow YAMLs are stored as `.yaml` files in this directory and
+ * compile-time embedded by reading them at build time. We don't use a
+ * code-generator (matches the rest of the codebase that avoids generated
+ * files); instead, the build's `copy-assets` script copies the .yaml
+ * files into `dist/workflows/defaults/`, and this module reads them at
+ * import time from `__dirname`.
+ *
+ * Bundled workflows (v1):
+ *   - spec-implement.yaml   — implement an unimplemented spec
+ *   - spec-fix.yaml         — fix a drifted / broken link
+ *   - spec-verify.yaml      — run verification across `implemented` links
+ *   - spec-relink.yaml      — re-attach an orphaned link
+ *
+ * See workflow-discovery.ts for the three-tier precedence model.
+ */
+export interface BundledWorkflow {
+    /** Filename stem (no .yaml extension). */
+    name: string;
+    /** Raw YAML source. */
+    yaml: string;
+}
+export declare const bundledDefaults: BundledWorkflow[];
+//# sourceMappingURL=index.d.ts.map

package/dist/workflows/defaults/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflows/defaults/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AASD,eAAO,MAAM,eAAe,EAAE,eAAe,EAAmB,CAAC"}

package/dist/workflows/defaults/index.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Bundled default workflows.
+ *
+ * Workflow YAMLs are stored as `.yaml` files in this directory and
+ * compile-time embedded by reading them at build time. We don't use a
+ * code-generator (matches the rest of the codebase that avoids generated
+ * files); instead, the build's `copy-assets` script copies the .yaml
+ * files into `dist/workflows/defaults/`, and this module reads them at
+ * import time from `__dirname`.
+ *
+ * Bundled workflows (v1):
+ *   - spec-implement.yaml   — implement an unimplemented spec
+ *   - spec-fix.yaml         — fix a drifted / broken link
+ *   - spec-verify.yaml      — run verification across `implemented` links
+ *   - spec-relink.yaml      — re-attach an orphaned link
+ *
+ * See workflow-discovery.ts for the three-tier precedence model.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundledDefaults = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Lazy-loaded bundled defaults from `<dist|src>/workflows/defaults/*.yaml`.
+ * Populated on first read. Always re-reads from disk in tests where the
+ * file set may have been mutated; production callers call once at startup.
+ */
+let cached = null;
+exports.bundledDefaults = loadDefaults();
+function loadDefaults() {
+    if (cached)
+        return cached;
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(__dirname, { withFileTypes: true });
+    }
+    catch {
+        cached = [];
+        return cached;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const lower = entry.name.toLowerCase();
+        if (!lower.endsWith('.yaml') && !lower.endsWith('.yml'))
+            continue;
+        try {
+            const yaml = fs.readFileSync(path.join(__dirname, entry.name), 'utf-8');
+            const stem = entry.name.replace(/\.(ya?ml)$/i, '');
+            out.push({ name: stem, yaml });
+        }
+        catch {
+            // Skip unreadable files; discovery will surface the gap on next load.
+        }
+    }
+    cached = out;
+    return cached;
+}
+//# sourceMappingURL=index.js.map

package/dist/workflows/defaults/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/workflows/defaults/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,uCAAyB;AACzB,2CAA6B;AAS7B;;;;GAIG;AACH,IAAI,MAAM,GAA6B,IAAI,CAAC;AAE/B,QAAA,eAAe,GAAsB,YAAY,EAAE,CAAC;AAEjE,SAAS,YAAY;IACnB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,IAAI,OAAoB,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAS;QAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAS;QAClE,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YACxE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;YACnD,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;QACxE,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,CAAC;IACb,OAAO,MAAM,CAAC;AAChB,CAAC"}