@opellen/scaff 0.1.11

package/dist/cli.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { install, dryRun } from "./installer.js";
+import { PLATFORM_IDS, DEFAULT_PLATFORM, isValidPlatform } from "./platforms/index.js";
+import { showWelcome } from "./ui/welcome.js";
+import { selectPlatforms } from "./prompts/platform-select.js";
+import { t } from "./i18n/index.js";
+import chalk from "chalk";
+import { brand } from "./ui/colors.js";
+import { extend } from "./extend.js";
+function printUsage() {
+    console.log(`
+scaff — Lightweight context scaffolding for AI coding
+
+Usage:
+  scaff init [options]
+  scaff extend <path> [--force] [--root <dir>]
+
+Options:
+  --docs <dir>      Documentation directory (default: docs)
+  --codebase <dir>  Codebase directory (default: .)
+  --tools <list>    Target platforms: comma-separated, or "all" (default: claude)
+                    Available: ${PLATFORM_IDS.join(", ")}
+  --no-subagent     Disable subagent delegation (enabled by default)
+  --root <dir>      Target directory (default: cwd)
+  --force           Overwrite existing files without prompting
+  --dry-run         Preview without writing files
+  -h, --help        Show this help
+
+Commands:
+  init              Install scaff into the current project
+  extend <path>     Install a local extension (reads <path>/scaff-extend.yml)
+`);
+}
+function parseArgs(argv) {
+    let command = null;
+    const positional = [];
+    let docsDir = "docs";
+    let codebaseDir = ".";
+    let tools = null;
+    let subagent = true;
+    let root = process.cwd();
+    let force = false;
+    let isDryRun = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            help = true;
+        }
+        else if (arg === "--docs") {
+            const next = argv[++i];
+            if (!next) {
+                console.error("Error: --docs requires a directory path");
+                process.exit(1);
+            }
+            docsDir = next;
+        }
+        else if (arg === "--codebase") {
+            const next = argv[++i];
+            if (!next) {
+                console.error("Error: --codebase requires a directory path");
+                process.exit(1);
+            }
+            codebaseDir = next;
+        }
+        else if (arg === "--tools") {
+            const next = argv[++i];
+            if (!next) {
+                console.error("Error: --tools requires a platform list");
+                process.exit(1);
+            }
+            if (next === "all") {
+                tools = [...PLATFORM_IDS];
+            }
+            else {
+                tools = next.split(",").map((id) => id.trim());
+                for (const id of tools) {
+                    if (!isValidPlatform(id)) {
+                        console.error(`Error: unknown platform "${id}". Available: ${PLATFORM_IDS.join(", ")}`);
+                        process.exit(1);
+                    }
+                }
+            }
+        }
+        else if (arg === "--no-subagent") {
+            subagent = false;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--dry-run") {
+            isDryRun = true;
+        }
+        else if (arg === "--root") {
+            const next = argv[++i];
+            if (!next) {
+                console.error("Error: --root requires a directory path");
+                process.exit(1);
+            }
+            root = resolve(next);
+        }
+        else if (!arg.startsWith("-")) {
+            if (command === null) {
+                command = arg;
+            }
+            else {
+                positional.push(arg);
+            }
+        }
+        else {
+            console.error(`Unknown option: ${arg}`);
+            printUsage();
+            process.exit(1);
+        }
+    }
+    return { command, positional, docsDir, codebaseDir, tools, subagent, root, force, dryRun: isDryRun, help };
+}
+async function runExtend(args) {
+    const extPath = args.positional[0];
+    if (!extPath) {
+        console.error("Error: scaff extend requires a path argument");
+        printUsage();
+        process.exit(1);
+    }
+    const resolvedExt = resolve(extPath);
+    if (!existsSync(resolvedExt)) {
+        console.error(`Error: extension path does not exist: ${resolvedExt}`);
+        process.exit(1);
+    }
+    if (!existsSync(args.root)) {
+        console.error(`Error: target directory does not exist: ${args.root}`);
+        process.exit(1);
+    }
+    try {
+        const result = await extend(resolvedExt, {
+            force: args.force,
+            root: args.root,
+        });
+        if (result.commandsAdded.length > 0) {
+            console.log(`${chalk.green("\u2713")} Commands added: ${result.commandsAdded.join(", ")}`);
+        }
+        if (result.commandsSkipped.length > 0) {
+            console.log(`${chalk.yellow("~")} Commands skipped: ${result.commandsSkipped.join(", ")}`);
+        }
+        if (result.hooksApplied.length > 0) {
+            console.log(`${chalk.green("\u2713")} Hooks applied: ${result.hooksApplied.join(", ")}`);
+        }
+        if (result.dependenciesChecked.length > 0) {
+            console.log(`${chalk.green("\u2713")} Dependencies: all found`);
+        }
+        process.exit(0);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help || !args.command) {
+        printUsage();
+        process.exit(args.help ? 0 : 1);
+    }
+    if (args.command === "extend") {
+        await runExtend(args);
+        return;
+    }
+    if (args.command !== "init") {
+        console.error(`Unknown command: ${args.command}`);
+        printUsage();
+        process.exit(1);
+    }
+    if (!existsSync(args.root)) {
+        console.error(`Error: target directory does not exist: ${args.root}`);
+        process.exit(1);
+    }
+    let tools;
+    if (args.tools) {
+        tools = args.tools;
+    }
+    else if (process.stdin.isTTY && !args.dryRun) {
+        await showWelcome();
+        tools = await selectPlatforms(args.root);
+    }
+    else {
+        tools = [DEFAULT_PLATFORM];
+    }
+    const config = {
+        tools,
+        subagent: args.subagent,
+        root: args.root,
+        docsDir: args.docsDir,
+        codebaseDir: args.codebaseDir,
+        force: args.force,
+    };
+    if (args.dryRun) {
+        const result = dryRun(config);
+        console.log(t("cli.dryRun") + "\n");
+        for (const file of result.files) {
+            console.log(`  ${chalk.green("+")} ${file}`);
+        }
+        return;
+    }
+    const result = await install(config);
+    console.log(t("cli.complete") + "\n");
+    if (result.files.length > 0) {
+        console.log(t("cli.installed"));
+        for (const file of result.files) {
+            console.log(`  ${chalk.green("+")} ${file}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log("\n" + t("cli.skipped"));
+        for (const file of result.skipped) {
+            console.log(`  ${chalk.yellow("~")} ${file}`);
+        }
+    }
+    console.log("\n" + brand(t("cli.nextSteps")));
+    console.log("  " + chalk.dim("1.") + " " + t("cli.step1"));
+    console.log("  " + chalk.dim("2.") + " " + t("cli.step2").replace("{cmd}", brand("/scaff:scout")));
+    process.exit(0);
+}
+main();

package/dist/extend.d.ts

@@ -0,0 +1,12 @@
+export interface ExtendOptions {
+    force: boolean;
+    root: string;
+}
+export type PromptFn = (question: string) => Promise<string>;
+export interface ExtendResult {
+    commandsAdded: string[];
+    commandsSkipped: string[];
+    hooksApplied: string[];
+    dependenciesChecked: string[];
+}
+export declare function extend(extensionPath: string, opts: ExtendOptions, promptFn?: PromptFn): Promise<ExtendResult>;

package/dist/extend.js

@@ -0,0 +1,242 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, } from "node:fs";
+import { join, dirname, isAbsolute, resolve } from "node:path";
+import { execSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { parse as parseYaml } from "yaml";
+import { injectHooks } from "./hook-parser.js";
+function createDefaultPrompt() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let closed = false;
+    rl.on("close", () => {
+        closed = true;
+    });
+    const prompt = (question) => {
+        if (closed)
+            return Promise.resolve("");
+        return new Promise((resolveP) => {
+            rl.question(question, (answer) => {
+                resolveP(answer.trim().toLowerCase());
+            });
+            rl.once("close", () => resolveP(""));
+        });
+    };
+    return { prompt, close: () => rl.close() };
+}
+function readManifest(extensionPath) {
+    const manifestPath = join(extensionPath, "scaff-extend.yml");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Missing scaff-extend.yml at ${manifestPath}`);
+    }
+    const raw = readFileSync(manifestPath, "utf-8");
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse scaff-extend.yml: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("scaff-extend.yml must be a YAML mapping");
+    }
+    return validateManifest(parsed);
+}
+function validateManifest(raw) {
+    if (typeof raw.name !== "string" || !raw.name) {
+        throw new Error("scaff-extend.yml: 'name' is required");
+    }
+    if (typeof raw.extends !== "string" || !raw.extends) {
+        throw new Error("scaff-extend.yml: 'extends' is required");
+    }
+    if (raw.extends !== "scaff") {
+        throw new Error(`scaff-extend.yml: 'extends' must be "scaff" (got "${raw.extends}"). Extension chains are not supported yet.`);
+    }
+    const commands = [];
+    if (raw.commands !== undefined) {
+        if (!Array.isArray(raw.commands)) {
+            throw new Error("scaff-extend.yml: 'commands' must be a list");
+        }
+        for (const c of raw.commands) {
+            if (typeof c !== "string" || !c) {
+                throw new Error("scaff-extend.yml: each command must be a non-empty string");
+            }
+            commands.push(c);
+        }
+    }
+    const hooks = [];
+    if (raw.hooks !== undefined) {
+        if (!Array.isArray(raw.hooks)) {
+            throw new Error("scaff-extend.yml: 'hooks' must be a list");
+        }
+        for (const h of raw.hooks) {
+            if (!h || typeof h !== "object") {
+                throw new Error("scaff-extend.yml: each hook must be a mapping");
+            }
+            const hook = h;
+            if (typeof hook.id !== "string" || !hook.id) {
+                throw new Error("scaff-extend.yml: hook 'id' is required");
+            }
+            if (typeof hook.target !== "string" || !hook.target) {
+                throw new Error(`scaff-extend.yml: hook '${hook.id}' missing 'target'`);
+            }
+            const hasContent = hook.content !== undefined;
+            const hasFile = hook.file !== undefined;
+            if (hasContent && hasFile) {
+                throw new Error(`scaff-extend.yml: hook '${hook.id}' cannot have both 'content' and 'file'`);
+            }
+            if (!hasContent && !hasFile) {
+                throw new Error(`scaff-extend.yml: hook '${hook.id}' must have either 'content' or 'file'`);
+            }
+            if (hasContent && typeof hook.content !== "string") {
+                throw new Error(`scaff-extend.yml: hook '${hook.id}' 'content' must be a string`);
+            }
+            if (hasFile && typeof hook.file !== "string") {
+                throw new Error(`scaff-extend.yml: hook '${hook.id}' 'file' must be a string`);
+            }
+            hooks.push({
+                id: hook.id,
+                target: hook.target,
+                content: hasContent ? hook.content : undefined,
+                file: hasFile ? hook.file : undefined,
+            });
+        }
+    }
+    const dependencies = [];
+    if (raw.dependencies !== undefined) {
+        if (!Array.isArray(raw.dependencies)) {
+            throw new Error("scaff-extend.yml: 'dependencies' must be a list");
+        }
+        for (const d of raw.dependencies) {
+            if (!d || typeof d !== "object") {
+                throw new Error("scaff-extend.yml: each dependency must be a mapping");
+            }
+            const dep = d;
+            if (typeof dep.name !== "string" || !dep.name) {
+                throw new Error("scaff-extend.yml: dependency 'name' is required");
+            }
+            if (typeof dep.check !== "string" || !dep.check) {
+                throw new Error(`scaff-extend.yml: dependency '${dep.name}' missing 'check'`);
+            }
+            dependencies.push({ name: dep.name, check: dep.check });
+        }
+    }
+    return {
+        name: raw.name,
+        version: typeof raw.version === "string" ? raw.version : undefined,
+        extends: raw.extends,
+        requires: typeof raw.requires === "string" ? raw.requires : undefined,
+        commands,
+        hooks,
+        dependencies,
+    };
+}
+function checkDependencies(deps) {
+    for (const dep of deps) {
+        try {
+            execSync(dep.check, { stdio: "ignore" });
+        }
+        catch {
+            throw new Error(`Dependency '${dep.name}' not found (check: ${dep.check})`);
+        }
+    }
+}
+function commandTargetPath(root, name) {
+    return join(root, ".claude", "commands", "scaff", `${name}.md`);
+}
+function resolveWithinExtension(extensionPath, relPath) {
+    if (isAbsolute(relPath))
+        return relPath;
+    return resolve(extensionPath, relPath);
+}
+async function copyCommands(extensionPath, commands, root, force, ask) {
+    const copied = [];
+    const skipped = [];
+    let forceAll = force;
+    for (const name of commands) {
+        const src = join(extensionPath, "commands", `${name}.md`);
+        if (!existsSync(src)) {
+            throw new Error(`Missing command source file: ${src}`);
+        }
+        const dst = commandTargetPath(root, name);
+        if (existsSync(dst) && !forceAll) {
+            const answer = await ask(`File exists: ${dst}. Overwrite? (y/n/a) `);
+            if (answer === "a" || answer === "all") {
+                forceAll = true;
+            }
+            else if (answer !== "y" && answer !== "yes") {
+                skipped.push(name);
+                continue;
+            }
+        }
+        const dir = dirname(dst);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const content = readFileSync(src, "utf-8");
+        writeFileSync(dst, content, "utf-8");
+        copied.push(name);
+    }
+    return { copied, skipped };
+}
+function applyHooks(extensionPath, hooks, root) {
+    const applied = [];
+    const byTarget = new Map();
+    for (const hook of hooks) {
+        const list = byTarget.get(hook.target) ?? [];
+        list.push(hook);
+        byTarget.set(hook.target, list);
+    }
+    for (const [target, specs] of byTarget) {
+        const targetPath = isAbsolute(target) ? target : join(root, target);
+        if (!existsSync(targetPath)) {
+            throw new Error(`Hook target file not found: ${targetPath}`);
+        }
+        const original = readFileSync(targetPath, "utf-8");
+        const entries = specs.map((spec) => {
+            let content;
+            if (spec.content !== undefined) {
+                content = spec.content;
+            }
+            else {
+                const filePath = resolveWithinExtension(extensionPath, spec.file);
+                if (!existsSync(filePath)) {
+                    throw new Error(`Hook '${spec.id}' file not found: ${filePath}`);
+                }
+                content = readFileSync(filePath, "utf-8");
+            }
+            // Strip trailing newline so injected content fits cleanly between markers.
+            if (content.endsWith("\n")) {
+                content = content.slice(0, -1);
+            }
+            return { id: spec.id, content };
+        });
+        const next = injectHooks(original, entries);
+        writeFileSync(targetPath, next, "utf-8");
+        for (const spec of specs)
+            applied.push(spec.id);
+    }
+    return applied;
+}
+export async function extend(extensionPath, opts, promptFn) {
+    if (!existsSync(extensionPath)) {
+        throw new Error(`Extension path does not exist: ${extensionPath}`);
+    }
+    const manifest = readManifest(extensionPath);
+    const deps = manifest.dependencies ?? [];
+    checkDependencies(deps);
+    const defaultPrompt = promptFn ? null : createDefaultPrompt();
+    const ask = promptFn ?? defaultPrompt.prompt;
+    let copyResult;
+    try {
+        copyResult = await copyCommands(extensionPath, manifest.commands ?? [], opts.root, opts.force, ask);
+    }
+    finally {
+        defaultPrompt?.close();
+    }
+    const hooksApplied = applyHooks(extensionPath, manifest.hooks ?? [], opts.root);
+    return {
+        commandsAdded: copyResult.copied,
+        commandsSkipped: copyResult.skipped,
+        hooksApplied,
+        dependenciesChecked: deps.map((d) => d.name),
+    };
+}

package/dist/hook-parser.d.ts

@@ -0,0 +1,15 @@
+export interface HookEntry {
+    id: string;
+    content: string;
+}
+/**
+ * Validate that a file has properly paired hook markers.
+ * Returns list of hook ids found.
+ */
+export declare function findHookPoints(fileContent: string): string[];
+/**
+ * Inject hook content into a file's text.
+ * Returns the modified text.
+ * Throws on errors (missing markers, mismatched pairs, non-empty hooks).
+ */
+export declare function injectHooks(fileContent: string, hooks: HookEntry[]): string;

package/dist/hook-parser.js

@@ -0,0 +1,95 @@
+const HOOK_BEGIN = /^\s*<!--\s*@hook\s+(\S+)\s*-->/;
+const HOOK_END = /^\s*<!--\s*@end-hook\s+(\S+)\s*-->/;
+/**
+ * Validate that a file has properly paired hook markers.
+ * Returns list of hook ids found.
+ */
+export function findHookPoints(fileContent) {
+    const ids = [];
+    const lines = fileContent.split("\n");
+    let openId = null;
+    for (const line of lines) {
+        const beginMatch = line.match(HOOK_BEGIN);
+        const endMatch = line.match(HOOK_END);
+        if (beginMatch) {
+            if (openId !== null) {
+                throw new Error(`Unclosed hook '${openId}'`);
+            }
+            openId = beginMatch[1];
+        }
+        else if (endMatch) {
+            const endId = endMatch[1];
+            if (openId === null) {
+                throw new Error(`Unexpected hook end '${endId}'`);
+            }
+            if (endId !== openId) {
+                throw new Error(`Mismatched hook end: expected '${openId}', got '${endId}'`);
+            }
+            ids.push(openId);
+            openId = null;
+        }
+    }
+    if (openId !== null) {
+        throw new Error(`Unclosed hook '${openId}'`);
+    }
+    return ids;
+}
+/**
+ * Inject hook content into a file's text.
+ * Returns the modified text.
+ * Throws on errors (missing markers, mismatched pairs, non-empty hooks).
+ */
+export function injectHooks(fileContent, hooks) {
+    if (hooks.length === 0) {
+        return fileContent;
+    }
+    const lines = fileContent.split("\n");
+    const result = [];
+    const injected = new Set();
+    const hookMap = new Map(hooks.map((h) => [h.id, h.content]));
+    let openId = null;
+    let openLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const beginMatch = line.match(HOOK_BEGIN);
+        const endMatch = line.match(HOOK_END);
+        if (beginMatch) {
+            if (openId !== null) {
+                throw new Error(`Unclosed hook '${openId}'`);
+            }
+            openId = beginMatch[1];
+            openLine = i;
+            result.push(line);
+        }
+        else if (endMatch) {
+            const endId = endMatch[1];
+            if (openId === null) {
+                throw new Error(`Unexpected hook end '${endId}'`);
+            }
+            if (endId !== openId) {
+                throw new Error(`Mismatched hook end: expected '${openId}', got '${endId}'`);
+            }
+            if (i !== openLine + 1) {
+                throw new Error(`Hook '${openId}' already has content`);
+            }
+            if (hookMap.has(openId)) {
+                result.push(hookMap.get(openId));
+                injected.add(openId);
+            }
+            result.push(line);
+            openId = null;
+        }
+        else {
+            result.push(line);
+        }
+    }
+    if (openId !== null) {
+        throw new Error(`Unclosed hook '${openId}'`);
+    }
+    for (const hook of hooks) {
+        if (!injected.has(hook.id)) {
+            throw new Error(`Hook point '${hook.id}' not found in file`);
+        }
+    }
+    return result.join("\n");
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,5 @@
+import { type Locale, type MessageKey } from "./messages.js";
+export declare function getLocale(): Locale;
+export declare function setLocale(locale: Locale): void;
+export declare function t(key: MessageKey): string;
+export type { Locale, MessageKey };

package/dist/i18n/index.js

@@ -0,0 +1,20 @@
+import { messages } from "./messages.js";
+function detectLocale() {
+    const raw = process.env.LC_ALL ||
+        process.env.LC_MESSAGES ||
+        process.env.LANG ||
+        "";
+    if (raw.startsWith("ko"))
+        return "ko";
+    return "en";
+}
+let current = detectLocale();
+export function getLocale() {
+    return current;
+}
+export function setLocale(locale) {
+    current = locale;
+}
+export function t(key) {
+    return messages[current][key];
+}

package/dist/i18n/messages.d.ts

@@ -0,0 +1,28 @@
+declare const en: {
+    readonly "welcome.tagline": "Context scaffolding for AI coding. Just markdown.";
+    readonly "welcome.setsUp": "Installs:";
+    readonly "welcome.skills": "Slash commands";
+    readonly "welcome.commands": "Agent skills";
+    readonly "welcome.pressEnter": "Press Enter to select tools.";
+    readonly "select.message": "Select tools";
+    readonly "select.typeToFilter": "type to filter";
+    readonly "select.detected": "detected";
+    readonly "select.selected": "selected";
+    readonly "select.none": "none";
+    readonly "select.error.empty": "Select at least one tool.";
+    readonly "select.hint": "↑↓ navigate • Space toggle • Backspace remove • Enter confirm";
+    readonly "select.available": "available";
+    readonly "select.selectedLabel": "Selected:";
+    readonly "select.searchLabel": "Search:";
+    readonly "cli.dryRun": "Dry run — files that would be created:";
+    readonly "cli.complete": "scaff init complete.";
+    readonly "cli.installed": "Installed files:";
+    readonly "cli.skipped": "Skipped (use --force to overwrite):";
+    readonly "cli.nextSteps": "What's next:";
+    readonly "cli.step1": "Review installed files";
+    readonly "cli.step2": "Run {cmd}";
+};
+export type MessageKey = keyof typeof en;
+export type Locale = "en" | "ko";
+export declare const messages: Record<Locale, Record<MessageKey, string>>;
+export {};