@opellen/opengoal 1.0.0

package/dist/cli.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { install, dryRun, detectStale, removeStale } from "./installer.js";
+import { DEFAULT_PREFIX } from "./templates.js";
+import { PLATFORM_IDS, DEFAULT_PLATFORM, isValidPlatform, detectInstalledPlatforms } 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 { goal, title } from "./ui/colors.js";
+import { extend } from "./extend.js";
+function printUsage() {
+    console.log(`
+opengoal — Goal-centric AI harness. Open structure, clear present.
+
+Usage:
+  opengoal init [options]
+  opengoal 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)
+  --prefix <name>   Slash-command prefix (default: opgl)
+  --from-prefix <name>  Also detect stale files from this previous prefix
+                    (the legacy "scaff" prefix is always checked)
+  --force           Overwrite existing files without prompting
+  -y, --yes         Auto-confirm with detected platforms (skip interactive selection)
+  --dry-run         Preview without writing files
+  -h, --help        Show this help
+
+Commands:
+  init              Install opengoal into the current project
+  extend <path>     Install a local extension (reads <path>/opengoal-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 prefix = DEFAULT_PREFIX;
+    let prefixExplicit = false;
+    let fromPrefix = null;
+    let fromPrefixExplicit = false;
+    let force = false;
+    let yes = 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 === "-y" || arg === "--yes") {
+            yes = 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 === "--prefix") {
+            const next = argv[++i];
+            if (!next) {
+                console.error("Error: --prefix requires a value");
+                process.exit(1);
+            }
+            if (!/^[a-z][a-z0-9-]{0,15}$/.test(next)) {
+                console.error(`Error: invalid --prefix "${next}". Must start with a lowercase letter and contain only lowercase letters, digits, and hyphens, 1-16 characters long.`);
+                process.exit(1);
+            }
+            prefix = next;
+            prefixExplicit = true;
+        }
+        else if (arg === "--from-prefix") {
+            const next = argv[++i];
+            if (!next) {
+                console.error("Error: --from-prefix requires a value");
+                process.exit(1);
+            }
+            if (!/^[a-z][a-z0-9-]{0,15}$/.test(next)) {
+                console.error(`Error: invalid --from-prefix "${next}". Must start with a lowercase letter and contain only lowercase letters, digits, and hyphens, 1-16 characters long.`);
+                process.exit(1);
+            }
+            fromPrefix = next;
+            fromPrefixExplicit = true;
+        }
+        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, prefix, prefixExplicit, fromPrefix, fromPrefixExplicit, force, yes, dryRun: isDryRun, help };
+}
+async function runExtend(args) {
+    const extPath = args.positional[0];
+    if (!extPath) {
+        console.error("Error: opengoal 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,
+            prefix: args.prefixExplicit ? args.prefix : undefined,
+        });
+        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 (args.yes) {
+        const detected = detectInstalledPlatforms(args.root);
+        tools = detected.length > 0 ? detected : [DEFAULT_PLATFORM];
+        console.log(chalk.dim(`Auto-selected: ${tools.join(", ")}`));
+    }
+    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,
+        prefix: args.prefix,
+        force: args.force,
+    };
+    const oldPrefixes = Array.from(new Set(["scaff", ...(args.fromPrefixExplicit ? [args.fromPrefix] : [])])).filter((p) => p !== config.prefix);
+    const stale = detectStale(config, oldPrefixes);
+    if (args.dryRun) {
+        const result = dryRun(config);
+        console.log(t("cli.dryRun") + "\n");
+        for (const file of result.files) {
+            console.log(`  ${chalk.green("+")} ${file}`);
+        }
+        if (stale.length > 0) {
+            console.log("\nStale files from a previous prefix (would be removed):");
+            for (const entry of stale) {
+                console.log(`  ${chalk.red("-")} ${entry.dst}`);
+            }
+        }
+        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}`);
+        }
+    }
+    if (stale.length > 0) {
+        console.log("\nStale files from a previous prefix:");
+        for (const entry of stale) {
+            console.log(`  ${chalk.yellow("!")} ${entry.dst}`);
+        }
+        const { removed, kept } = await removeStale(config, stale);
+        if (removed.length > 0) {
+            console.log("\nRemoved stale files:");
+            for (const file of removed) {
+                console.log(`  ${chalk.red("-")} ${file}`);
+            }
+        }
+        if (kept.length > 0) {
+            console.log("\nLeft in place (not removed):");
+            for (const file of kept) {
+                console.log(`  ${chalk.dim("~")} ${file}`);
+            }
+        }
+    }
+    console.log("\n" + title(t("cli.nextSteps")));
+    console.log("  " + chalk.dim("1.") + " " + t("cli.step1"));
+    console.log("  " + chalk.dim("2.") + " " + t("cli.step2").replace("{cmd}", goal(`/${args.prefix}:scout`)));
+    process.exit(0);
+}
+main();

package/dist/extend.d.ts

@@ -0,0 +1,13 @@
+export interface ExtendOptions {
+    force: boolean;
+    root: string;
+    prefix?: 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,286 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, } 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";
+import { getAdapter } from "./platforms/index.js";
+// `index.ts` only exposes adapters by id (no per-adapter named exports), so
+// look the claude adapter up once here. It's always present in the adapter
+// map (it's the platform default), so this can never be undefined.
+const claude = getAdapter("claude");
+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, "opengoal-extend.yml");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Missing opengoal-extend.yml at ${manifestPath}`);
+    }
+    const raw = readFileSync(manifestPath, "utf-8");
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse opengoal-extend.yml: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error("opengoal-extend.yml must be a YAML mapping");
+    }
+    return validateManifest(parsed);
+}
+function validateManifest(raw) {
+    if (typeof raw.name !== "string" || !raw.name) {
+        throw new Error("opengoal-extend.yml: 'name' is required");
+    }
+    if (typeof raw.extends !== "string" || !raw.extends) {
+        throw new Error("opengoal-extend.yml: 'extends' is required");
+    }
+    if (raw.extends !== "opengoal") {
+        throw new Error(`opengoal-extend.yml: 'extends' must be "opengoal" (got "${raw.extends}"). Extension chains are not supported yet.`);
+    }
+    const commands = [];
+    if (raw.commands !== undefined) {
+        if (!Array.isArray(raw.commands)) {
+            throw new Error("opengoal-extend.yml: 'commands' must be a list");
+        }
+        for (const c of raw.commands) {
+            if (typeof c !== "string" || !c) {
+                throw new Error("opengoal-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("opengoal-extend.yml: 'hooks' must be a list");
+        }
+        for (const h of raw.hooks) {
+            if (!h || typeof h !== "object") {
+                throw new Error("opengoal-extend.yml: each hook must be a mapping");
+            }
+            const hook = h;
+            if (typeof hook.id !== "string" || !hook.id) {
+                throw new Error("opengoal-extend.yml: hook 'id' is required");
+            }
+            if (typeof hook.target !== "string" || !hook.target) {
+                throw new Error(`opengoal-extend.yml: hook '${hook.id}' missing 'target'`);
+            }
+            const hasContent = hook.content !== undefined;
+            const hasFile = hook.file !== undefined;
+            if (hasContent && hasFile) {
+                throw new Error(`opengoal-extend.yml: hook '${hook.id}' cannot have both 'content' and 'file'`);
+            }
+            if (!hasContent && !hasFile) {
+                throw new Error(`opengoal-extend.yml: hook '${hook.id}' must have either 'content' or 'file'`);
+            }
+            if (hasContent && typeof hook.content !== "string") {
+                throw new Error(`opengoal-extend.yml: hook '${hook.id}' 'content' must be a string`);
+            }
+            if (hasFile && typeof hook.file !== "string") {
+                throw new Error(`opengoal-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("opengoal-extend.yml: 'dependencies' must be a list");
+        }
+        for (const d of raw.dependencies) {
+            if (!d || typeof d !== "object") {
+                throw new Error("opengoal-extend.yml: each dependency must be a mapping");
+            }
+            const dep = d;
+            if (typeof dep.name !== "string" || !dep.name) {
+                throw new Error("opengoal-extend.yml: dependency 'name' is required");
+            }
+            if (typeof dep.check !== "string" || !dep.check) {
+                throw new Error(`opengoal-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})`);
+        }
+    }
+}
+/**
+ * Directory the claude adapter installs commands under, relative to a
+ * project root (currently `.claude/commands`). Derived from the adapter's
+ * own commandPath rather than hard-coded, so it stays in sync if the
+ * adapter's layout ever changes.
+ */
+function claudeCommandsDir(root) {
+    const probePath = claude.commandPath("__probe__", "__prefix__");
+    return join(root, dirname(dirname(probePath)));
+}
+/**
+ * Detects the installed slash-command prefix by inspecting what's actually
+ * on disk under the claude adapter's command directory. A single
+ * subdirectory there is taken as the installed prefix. There is no state
+ * file to consult (this project guarantees zero runtime after install), so
+ * when the directory is missing, empty, or ambiguous we fail with a clear
+ * message rather than guess.
+ */
+function detectPrefix(root) {
+    const commandsDir = claudeCommandsDir(root);
+    if (!existsSync(commandsDir)) {
+        throw new Error(`Cannot detect installed command prefix: ${commandsDir} does not exist. Pass --prefix explicitly.`);
+    }
+    const subdirs = readdirSync(commandsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    if (subdirs.length === 0) {
+        throw new Error(`Cannot detect installed command prefix: no subdirectories found under ${commandsDir}. Pass --prefix explicitly.`);
+    }
+    if (subdirs.length > 1) {
+        throw new Error(`Cannot detect installed command prefix: multiple candidates found under ${commandsDir} (${subdirs.sort().join(", ")}). Pass --prefix explicitly.`);
+    }
+    return subdirs[0];
+}
+function resolvePrefix(root, explicit) {
+    return explicit ?? detectPrefix(root);
+}
+function resolveWithinExtension(extensionPath, relPath) {
+    if (isAbsolute(relPath))
+        return relPath;
+    return resolve(extensionPath, relPath);
+}
+async function copyCommands(extensionPath, commands, root, prefix, 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 = join(root, claude.commandPath(name, prefix));
+        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 commands = manifest.commands ?? [];
+    // Only resolve/detect a prefix when there are commands to install — an
+    // extension that only applies hooks or checks dependencies has no need
+    // for one, and shouldn't fail just because no prefix can be found.
+    const prefix = commands.length > 0 ? resolvePrefix(opts.root, opts.prefix) : "";
+    const defaultPrompt = promptFn ? null : createDefaultPrompt();
+    const ask = promptFn ?? defaultPrompt.prompt;
+    let copyResult;
+    try {
+        copyResult = await copyCommands(extensionPath, commands, opts.root, prefix, 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;