@opellen/scaff 0.1.15 → 0.1.16

package/dist/templates.js

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderTemplate } from "./marker.js";
+import { getAdapters } from "./platforms/index.js";
+import { skillInstallPath, formatSkill } from "./skills/generate.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(__dirname, "..", "templates");
+// Installed CLI version — injected into skill metadata.generatedBy.
+// Read once at module load from the shipped package.json.
+const SCAFF_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+const COMMAND_TEMPLATES = [
+    "scout", "goal", "context", "design",
+    "roadmap", "verify", "recap", "overview", "go",
+];
+const SKILL_TEMPLATES = [
+    { src: "skills/scaff-subagent/SKILL.md", skillName: "scaff-subagent" },
+    { src: "skills/scaff-flow/SKILL.md", skillName: "scaff-flow" },
+];
+function parseMeta(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
+    if (!fmMatch)
+        return { name: "", description: "" };
+    const fm = fmMatch[1];
+    const nameMatch = fm.match(/name:\s*"?scaff:(\w+)"?/);
+    const descMatch = fm.match(/description:\s*"([^"]+)"/);
+    const categoryMatch = fm.match(/category:\s*(\S+)/);
+    const tagsMatch = fm.match(/tags:\s*\[([^\]]*)\]/);
+    const tags = tagsMatch
+        ? tagsMatch[1]
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+            .filter(Boolean)
+        : undefined;
+    return {
+        name: nameMatch?.[1] ?? "",
+        description: descMatch?.[1] ?? "",
+        category: categoryMatch?.[1],
+        tags,
+    };
+}
+export function resolveTemplates(config) {
+    const adapters = getAdapters(config.tools);
+    const entries = [];
+    const commandMetas = COMMAND_TEMPLATES.map((cmd) => {
+        const src = `commands/${cmd}.md`;
+        const rawContent = readFileSync(join(TEMPLATE_DIR, src), "utf-8");
+        return { cmd, src, rawContent, meta: parseMeta(rawContent) };
+    });
+    const skillContents = SKILL_TEMPLATES.map((skill) => ({
+        ...skill,
+        rawContent: readFileSync(join(TEMPLATE_DIR, skill.src), "utf-8"),
+    }));
+    for (const adapter of adapters) {
+        if (adapter.supportsCommands !== false) {
+            for (const { cmd, src, rawContent, meta } of commandMetas) {
+                entries.push({ src, dst: adapter.commandPath(cmd), adapter, meta, rawContent });
+            }
+        }
+        for (const skill of skillContents) {
+            entries.push({
+                src: skill.src,
+                dst: skillInstallPath(adapter, skill.skillName),
+                adapter,
+                meta: { name: skill.skillName, description: "" },
+                rawContent: skill.rawContent,
+            });
+        }
+    }
+    return entries;
+}
+export function renderFile(entry, config) {
+    const content = entry.rawContent.replace(/\r\n/g, "\n");
+    const rendered = renderTemplate(content, {
+        conditions: {
+            subagent: config.subagent,
+        },
+    });
+    const substituted = rendered
+        .replace(/\$DocsDir/g, config.docsDir)
+        .replace(/\$CodebaseDir/g, config.codebaseDir)
+        .replace(/\$ScaffVersion/g, SCAFF_VERSION);
+    if (entry.src.startsWith("skills/")) {
+        return formatSkill(substituted);
+    }
+    return entry.adapter.formatCommand(substituted, entry.meta);
+}

package/dist/ui/ascii-logo.d.ts

@@ -0,0 +1,6 @@
+export declare const SCAFF_LOGO: {
+    readonly frame: readonly ["  ████        ████  ", "  █              █  ", "█████          █████", "  █              █  ", "  █              █  ", "  █              █  ", "  █              █  ", "  █              █  ", "█████          █████", "  █              █  ", "  ████        ████  "];
+    readonly inner: readonly ["                    ", "                    ", "     ██      ████   ", "      ▒█    █▒      ", "       ▒█  █▒       ", "        ▒██▒        ", "       ▒█  █▒       ", "      ▒█    █▒      ", "   ████      ██     ", "                    ", "                    "];
+};
+export declare const SCAFF_LOGO_WIDTH: number;
+export declare const SCAFF_LOGO_HEIGHT: 11;

package/dist/ui/ascii-logo.js

@@ -0,0 +1,38 @@
+// Two-layer logo. Layers are overlaid at render time: any non-space char in
+// `inner` wins over `frame`. This lets the same block char (█, ▒, ...) carry
+// a different color depending on which layer it belongs to, without a parallel
+// mask array to keep in sync.
+//
+// Palette: █ (full), ▓ (dark), ▒ (medium), ░ (light) — shade blocks give a
+// pseudo-anti-aliased gradient on diagonal edges that renders uniformly across
+// monospace fonts, unlike slash/diagonal glyphs (╲ ╱ ╳) which frequently break.
+export const SCAFF_LOGO = {
+    frame: [
+        "  ████        ████  ",
+        "  █              █  ",
+        "█████          █████",
+        "  █              █  ",
+        "  █              █  ",
+        "  █              █  ",
+        "  █              █  ",
+        "  █              █  ",
+        "█████          █████",
+        "  █              █  ",
+        "  ████        ████  ",
+    ],
+    inner: [
+        "                    ",
+        "                    ",
+        "     ██      ████   ",
+        "      ▒█    █▒      ",
+        "       ▒█  █▒       ",
+        "        ▒██▒        ",
+        "       ▒█  █▒       ",
+        "      ▒█    █▒      ",
+        "   ████      ██     ",
+        "                    ",
+        "                    ",
+    ],
+};
+export const SCAFF_LOGO_WIDTH = SCAFF_LOGO.frame[0].length;
+export const SCAFF_LOGO_HEIGHT = SCAFF_LOGO.frame.length;

package/dist/ui/colors.d.ts

@@ -0,0 +1,2 @@
+export declare const brand: import("chalk").ChalkInstance;
+export declare const brandInner: import("chalk").ChalkInstance;

package/dist/ui/colors.js

@@ -0,0 +1,3 @@
+import chalk from "chalk";
+export const brand = chalk.hex("#A8948B");
+export const brandInner = chalk.hex("#3C4C5C");

package/dist/ui/welcome.d.ts

@@ -0,0 +1 @@
+export declare function showWelcome(): Promise<void>;

package/dist/ui/welcome.js

@@ -0,0 +1,77 @@
+import chalk from "chalk";
+import { SCAFF_LOGO, SCAFF_LOGO_HEIGHT, SCAFF_LOGO_WIDTH } from "./ascii-logo.js";
+import { t } from "../i18n/index.js";
+import { brand, brandInner } from "./colors.js";
+export async function showWelcome() {
+    if (!process.stdin.isTTY)
+        return;
+    const cols = process.stdout.columns ?? 80;
+    const compact = cols < 60;
+    const lines = buildScreen(compact);
+    process.stdout.write("\n" + lines.join("\n") + "\n\n");
+    await waitForEnter();
+}
+function buildScreen(compact) {
+    const rightLines = [
+        brand.bold("Scaff"),
+        chalk.dim(t("welcome.tagline")),
+        "",
+        chalk.dim(t("welcome.setsUp")),
+        "  " + chalk.dim("•") + " " + t("welcome.skills"),
+        "  " + chalk.dim("•") + " " + t("welcome.commands"),
+        "",
+        brand(t("welcome.pressEnter")),
+    ];
+    if (compact) {
+        return rightLines;
+    }
+    const gap = "    ";
+    const totalRows = Math.max(SCAFF_LOGO_HEIGHT, rightLines.length);
+    const result = [];
+    for (let i = 0; i < totalRows; i++) {
+        const logo = i < SCAFF_LOGO_HEIGHT ? colorLogoRow(i) : " ".repeat(SCAFF_LOGO_WIDTH);
+        const text = i < rightLines.length ? rightLines[i] : "";
+        result.push(logo + gap + text);
+    }
+    return result;
+}
+function colorLogoRow(row) {
+    const frame = SCAFF_LOGO.frame[row];
+    const inner = SCAFF_LOGO.inner[row];
+    let result = "";
+    for (let j = 0; j < SCAFF_LOGO_WIDTH; j++) {
+        const innerCh = inner[j];
+        if (innerCh !== " ") {
+            result += brandInner(innerCh);
+            continue;
+        }
+        const frameCh = frame[j];
+        result += frameCh === " " ? " " : brand(frameCh);
+    }
+    return result;
+}
+function waitForEnter() {
+    return new Promise((resolve) => {
+        const { stdin } = process;
+        const wasRaw = stdin.isRaw ?? false;
+        stdin.setRawMode(true);
+        stdin.resume();
+        const onData = (buf) => {
+            const key = buf[0];
+            if (key === 0x0d || key === 0x0a) {
+                cleanup();
+                resolve();
+            }
+            else if (key === 0x03) {
+                cleanup();
+                process.exit(0);
+            }
+        };
+        const cleanup = () => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw);
+            stdin.pause();
+        };
+        stdin.on("data", onData);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opellen/scaff",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Agile, goal-centric AI harness. Just markdown.",
   "type": "module",
   "license": "MIT",

package/templates/commands/context.md

@@ -64,6 +64,7 @@ Creates `$DocsDir/CONTEXT.md`.
 - Tasks live in `$DocsDir/GOAL.md` `## Tasks`. Front-matter requires an `id` (slug format).
 - Implementation happens in `$CodebaseDir`.
 - Session progress: `/scaff:goal checkpoint` → `$DocsDir/CHECKPOINT.md` (overwritten per session).
+- Deferred discoveries: out-of-scope findings go to `$DocsDir/BACKLOG.md` (persistent parking lot).
 ```
 
 **Project-specific sections** — extend the skeleton with sections appropriate to the project:

package/templates/commands/goal.md

@@ -46,7 +46,8 @@ Creates `$DocsDir/GOAL.md`.
 5. Assess task granularity:
    - (tasks are complex, embed multiple implicit steps) => recommend `/scaff:goal breakdown` with 1-line rationale
    - (tasks are specific and actionable) => recommend `/scaff:design init` (implementation task) or `/scaff:go` (analysis task) with 1-line rationale
-6. Report: `"Created [GOAL.md]($DocsDir/GOAL.md)."`
+6. (goal created from a `$DocsDir/BACKLOG.md` item) => remove that item from BACKLOG.md (promotion = deletion).
+7. Report: `"Created [GOAL.md]($DocsDir/GOAL.md)."`
 
 GOAL.md format:
 ```yaml
@@ -192,5 +193,6 @@ Archives the current GOAL.md and its siblings.
    - (CHECKPOINT.md exists) => archive/CHECKPOINT.md
 5. If `$DocsDir/ROADMAP.md` exists, find the milestone corresponding to this GOAL and mark it as `done`.
 6. Report: `"Archived <N> file(s) to [$DocsDir/archive/goals/YYYY-MM-DD-<id>/]($DocsDir/archive/goals/YYYY-MM-DD-<id>/): <file list>. Set a new goal with /scaff:goal init."`
+7. (`$DocsDir/BACKLOG.md` has open items) => suggest promoting one as the next goal.
 
 > When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/scout.md

@@ -30,7 +30,8 @@ tags: [workflow, scaff, scout]
    - `$DocsDir/CONTEXT.md`, `$DocsDir/GOAL.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, `$DocsDir/ROADMAP.md`, `$DocsDir/CHECKPOINT.md`
    - A file read error means the file does not exist — mark it as "not present" and move on. **Do NOT retry failed reads.**
 2. If no GOAL.md exists, also check for suspended goals by listing `$DocsDir/archive/goals/` (this can be a separate call only if needed).
-3. Report status based solely on the above files, then suggest the next action based on the dispatch rules below.
+3. If no GOAL.md exists, also read `$DocsDir/BACKLOG.md` (skip this read when a GOAL is active).
+4. Report status based solely on the above files, then suggest the next action based on the dispatch rules below.
 
 ## State Dispatch
 
@@ -39,6 +40,7 @@ tags: [workflow, scaff, scout]
 - (CONTEXT.md only, no GOAL, no ROADMAP) => suggest `/scaff:goal init` or `/scaff:roadmap init`
 - (CONTEXT.md + ROADMAP.md, no GOAL) => suggest picking a milestone from ROADMAP.md and starting with `/scaff:goal init`
 - (no GOAL.md, suspended goals exist) => list suspended goals, suggest `/scaff:goal resume`
+- (no GOAL.md, BACKLOG.md has open items) => list items as next-goal candidates, suggest `/scaff:goal init`
 - (GOAL.md + CHECKPOINT.md) => show checkpoint summary, suggest `/scaff:go`
 - (GOAL.md, no DESIGN.md, implementation task) => suggest `/scaff:design init`
 - (GOAL.md, no DESIGN.md, analysis task) => suggest `/scaff:go`

package/templates/skills/scaff-flow/SKILL.md

@@ -92,6 +92,16 @@ When the current goal cannot proceed (discovered bug, missing dependency, blocki
 
 This preserves "one active GOAL.md at a time" — simpler than in-place stacking schemes.
 
+## Backlog Handling
+
+When a discovery falls outside the current goal's scope but does not block it (unrelated bug, improvement idea, tech debt):
+
+- (out-of-scope discovery, current GOAL can still progress) => offer to append a one-line entry to `$DocsDir/BACKLOG.md`, then continue the current task
+- (diagnosis is substantial) => record it in `$DocsDir/logs/` or `discussion/`; the backlog entry keeps only the one-liner + a pointer
+- Entry format: `- [ ] YYYY-MM-DD <one-liner> (found during <goal-id>)`
+
+Blocking discoveries => Blocker Handling (suspend); non-blocking => backlog.
+
 ## Self-Verification
 
 Before checking off a GOAL.md task or ROADMAP.md milestone as "done", verify: