@nac3/forge-cli 0.2.0-alpha.1

package/dist/core/gha_dispatcher.js

@@ -0,0 +1,198 @@
+/**
+ * GitHub Actions fallback dispatcher (PLAN connectivity).
+ *
+ * Per Pablo's decision (#4): when laptop is offline, mobile
+ * (or web) clients dispatch `yf <command>` to the user's
+ * GitHub repo via a yf-remote.yml workflow. Outputs land in
+ * a branch `_yujin/runs/<run_id>.json` that mobile polls.
+ *
+ * The workflow file is auto-committed when `yf projects add`
+ * registers a repo for the first time (per Pablo's "OK
+ * autonomia" on confirmation #2).
+ *
+ * This module gives:
+ *   - `yfRemoteWorkflowYaml()` -> the canonical workflow.
+ *   - `dispatchWorkflow(repo, command, args, token)` -> POST
+ *     to the GH API.
+ *   - `pollRunStatus(repo, runId, token)` -> SSE-like poller.
+ *
+ * ASCII-only.
+ */
+/** The canonical workflow yaml that Forge commits to user
+ *  repos on first registration. Idempotent on re-write. */
+export function yfRemoteWorkflowYaml() {
+    return `# AUTOGENERATED by Yujin Forge (yf projects add).
+# Lets the mobile / web client dispatch \`yf <command>\` here
+# when the user's laptop is offline. Output streams to a
+# branch \`_yujin/runs/<run_id>.json\`.
+
+name: yf-remote
+on:
+  workflow_dispatch:
+    inputs:
+      command:
+        description: 'yf subcommand to run (e.g. test, publish npm)'
+        required: true
+        type: string
+      args:
+        description: 'Additional CLI args (whitespace-separated)'
+        required: false
+        type: string
+        default: ''
+      run_id:
+        description: 'Unique id for this run (client-generated)'
+        required: true
+        type: string
+
+jobs:
+  remote:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+          cache: 'pnpm'
+
+      - name: Install Forge globally
+        run: pnpm install -g @nac3/forge-cli@alpha
+
+      - name: Install project deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Execute Forge command
+        id: yfrun
+        continue-on-error: true
+        run: |
+          yf \${{ inputs.command }} \${{ inputs.args }} \\
+            > /tmp/yf-run-stdout.txt \\
+            2> /tmp/yf-run-stderr.txt
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
+
+      - name: Publish run result to _yujin/runs branch
+        run: |
+          mkdir -p /tmp/run-output
+          cat <<EOF > /tmp/run-output/result.json
+          {
+            "run_id":   "\${{ inputs.run_id }}",
+            "command":  "\${{ inputs.command }}",
+            "args":     "\${{ inputs.args }}",
+            "exit":     "\${{ steps.yfrun.outputs.exit_code }}",
+            "stdout":   $(cat /tmp/yf-run-stdout.txt | jq -Rs .),
+            "stderr":   $(cat /tmp/yf-run-stderr.txt | jq -Rs .),
+            "completed_at": "$(date -u +%FT%TZ)"
+          }
+          EOF
+
+          git config user.email "forge@yujin.app"
+          git config user.name  "Yujin Forge (remote)"
+          git fetch origin _yujin/runs:_yujin/runs 2>/dev/null || true
+          git checkout -B _yujin/runs origin/_yujin/runs 2>/dev/null || git checkout --orphan _yujin/runs
+          git rm -rf . 2>/dev/null || true
+          mkdir -p runs
+          cp /tmp/run-output/result.json runs/\${{ inputs.run_id }}.json
+          git add runs/
+          git commit -m "yf-remote: \${{ inputs.run_id }}"
+          git push origin _yujin/runs
+`;
+}
+/** Generate a short, mostly-readable run_id. */
+export function generateRunId() {
+    const ts = Date.now().toString(36);
+    const rnd = Math.floor(Math.random() * 1e9).toString(36);
+    return ts + '-' + rnd;
+}
+/** Dispatch yf-remote on a GitHub repo. `repo` is the
+ *  "owner/name" string. Returns run_id + the workflow_run_id
+ *  when GH assigns one. */
+export async function dispatchWorkflow(repo, command, args, token) {
+    const runId = generateRunId();
+    const url = 'https://api.github.com/repos/' + repo + '/actions/workflows/yf-remote.yml/dispatches';
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 15000);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                authorization: 'token ' + token,
+                accept: 'application/vnd.github+json',
+                'content-type': 'application/json',
+                'user-agent': 'yujin-forge',
+            },
+            body: JSON.stringify({
+                ref: 'main',
+                inputs: { command, args, run_id: runId },
+            }),
+            signal: ctrl.signal,
+        });
+        if (res.status === 204 || res.status === 200) {
+            return { ok: true, run_id: runId };
+        }
+        const text = await res.text();
+        return { ok: false, error: 'github API ' + res.status + ': ' + text.slice(0, 200) };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Poll the _yujin/runs branch for the result JSON. Returns
+ *  null while pending, or the parsed JSON when ready. */
+export async function fetchRunResult(repo, runId, token) {
+    const url = 'https://api.github.com/repos/' + repo + '/contents/runs/' + runId + '.json?ref=_yujin/runs';
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 15000);
+    try {
+        const res = await fetch(url, {
+            headers: {
+                authorization: 'token ' + token,
+                accept: 'application/vnd.github+json',
+                'user-agent': 'yujin-forge',
+            },
+            signal: ctrl.signal,
+        });
+        if (res.status === 404) {
+            /* Run not yet committed; still in progress. */
+            return null;
+        }
+        if (res.status !== 200) {
+            return {
+                status: 'failure',
+                url: 'https://github.com/' + repo,
+                duration_seconds: 0,
+            };
+        }
+        const body = await res.json();
+        if (typeof body.content !== 'string')
+            return null;
+        const decoded = Buffer.from(body.content, 'base64').toString('utf-8');
+        const parsed = JSON.parse(decoded);
+        return {
+            status: parsed.exit === 0 ? 'success' : 'failure',
+            url: 'https://github.com/' + repo + '/actions',
+            duration_seconds: 0,
+            exit: parsed.exit,
+            stdout: parsed.stdout,
+            stderr: parsed.stderr,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=gha_dispatcher.js.map

package/dist/core/gha_dispatcher.js.map

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

package/dist/core/logger.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Yujin Forge logger -- per-scope configurable level + automatic
+ * redaction of sensitive fields, MVP of SQ.K from
+ * docs/PENDING_AND_SQ_LESSONS.md.
+ *
+ * Three layers:
+ *
+ *   1. createLogger(scope, opts?) -- factory.
+ *   2. setScopeLevel(scope, level) / setDefaultLevel(level) --
+ *      runtime knobs (no redeploy). Persisted across processes
+ *      via the override file at ~/.yujin-forge/logging.override.yml
+ *      (read on first call).
+ *   3. Per-message API: logger.trace/debug/info/warn/error/fatal,
+ *      logger.child({ subscope }), logger.isEnabled(level).
+ *
+ * Pure module -- no Node-only deps; runs on RN + Workers + CLI.
+ * The persistence file IS read via dynamic node:fs import when
+ * available, otherwise the host can call setScopeLevel directly.
+ *
+ * Out of scope for this MVP (TODO before SQ.K formal close):
+ *   - `yf log capture --since 10m` bundle command.
+ *   - Remote telemetry sink (HITO 4 endpoint).
+ *   - Sample-rate per level.
+ *
+ * ASCII-only.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export declare const LEVELS: readonly LogLevel[];
+export declare function setEnvironment(env: 'development' | 'production' | 'test'): void;
+export declare function setDefaultLevel(level: LogLevel): void;
+export declare function setScopeLevel(scope: string, level: LogLevel | null): void;
+export declare function setScopeRedactions(scope: string, keys: string[]): void;
+/** Resolve the active level for a scope. Falls through:
+ *    scope -> parent scopes (split by `.`) -> default. */
+export declare function levelForScope(scope: string): LogLevel;
+/** Resolve the redaction set for a scope: union of scope's own +
+ *  every ancestor + GLOBAL_REDACTIONS. */
+export declare function redactionsForScope(scope: string): Set<string>;
+export interface LogEntry {
+    ts: string;
+    level: LogLevel;
+    scope: string;
+    msg: string;
+    data?: Record<string, unknown>;
+    request_id?: string;
+}
+export interface LogSink {
+    write(entry: LogEntry): void;
+}
+export declare function consoleHumanSink(): LogSink;
+export declare function consoleJsonSink(): LogSink;
+/** In-memory ring buffer sink. Useful for tests + for a future
+ *  `yf log capture` bundle (read the buffer + dump). */
+export declare class RingSink implements LogSink {
+    capacity: number;
+    private buf;
+    constructor(capacity?: number);
+    write(e: LogEntry): void;
+    snapshot(): LogEntry[];
+    clear(): void;
+}
+export declare function addSink(sink: LogSink): void;
+export declare function clearSinks(): void;
+export declare function getSinks(): readonly LogSink[];
+export interface Logger {
+    scope: string;
+    isEnabled(level: LogLevel): boolean;
+    trace(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    fatal(msg: string, data?: Record<string, unknown>): void;
+    child(opts: {
+        subscope?: string;
+        request_id?: string;
+    }): Logger;
+}
+export declare function createLogger(scope: string, opts?: {
+    request_id?: string;
+}): Logger;
+/** Wrap an async function so its duration + outcome are
+ *  emitted at debug level (success) / warn level (failure). */
+export declare function withTimingLog<T>(logger: Logger, event: string, fn: () => Promise<T>, context?: Record<string, unknown>): Promise<T>;
+/** Test/CLI helper: reset all state. */
+export declare function resetLoggingForTests(): void;
+export declare function currentEnvironment(): string;
+export declare function currentDefaultLevel(): LogLevel;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

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

package/dist/core/logger.js

@@ -0,0 +1,245 @@
+/**
+ * Yujin Forge logger -- per-scope configurable level + automatic
+ * redaction of sensitive fields, MVP of SQ.K from
+ * docs/PENDING_AND_SQ_LESSONS.md.
+ *
+ * Three layers:
+ *
+ *   1. createLogger(scope, opts?) -- factory.
+ *   2. setScopeLevel(scope, level) / setDefaultLevel(level) --
+ *      runtime knobs (no redeploy). Persisted across processes
+ *      via the override file at ~/.yujin-forge/logging.override.yml
+ *      (read on first call).
+ *   3. Per-message API: logger.trace/debug/info/warn/error/fatal,
+ *      logger.child({ subscope }), logger.isEnabled(level).
+ *
+ * Pure module -- no Node-only deps; runs on RN + Workers + CLI.
+ * The persistence file IS read via dynamic node:fs import when
+ * available, otherwise the host can call setScopeLevel directly.
+ *
+ * Out of scope for this MVP (TODO before SQ.K formal close):
+ *   - `yf log capture --since 10m` bundle command.
+ *   - Remote telemetry sink (HITO 4 endpoint).
+ *   - Sample-rate per level.
+ *
+ * ASCII-only.
+ */
+export const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const LEVEL_RANK = {
+    trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5,
+};
+/** Default per-environment. The host sets the env via
+ *  `setEnvironment('development' | 'production' | 'test')`
+ *  on boot; the defaults flow from there. */
+const ENV_DEFAULTS = {
+    development: 'debug',
+    production: 'info',
+    test: 'warn',
+};
+let currentEnv = 'production';
+let defaultLevel = ENV_DEFAULTS.production;
+/** Per-scope override map. Mutated by setScopeLevel + by the
+ *  on-disk override file. */
+const scopeLevels = new Map();
+/** Per-scope redaction config. Each scope can declare keys
+ *  that, when present in a log payload, are replaced by
+ *  '[REDACTED]'. Layered: sub-scopes inherit from their
+ *  parent's redact set. */
+const scopeRedactions = new Map();
+/** Global redactions applied to every scope. Seeded with the
+ *  most dangerous keys: any token / secret / authorization
+ *  header that should never end up in a log line. */
+const GLOBAL_REDACTIONS = new Set([
+    'authorization', 'bearer', 'token', 'access_token',
+    'refresh_token', 'api_key', 'apiKey', 'secret', 'password',
+    'server_api_key', 'webhook_signature', 'x-polar-signature',
+]);
+export function setEnvironment(env) {
+    currentEnv = env;
+    defaultLevel = ENV_DEFAULTS[env] ?? 'info';
+}
+export function setDefaultLevel(level) {
+    defaultLevel = level;
+}
+export function setScopeLevel(scope, level) {
+    if (level === null) {
+        scopeLevels.delete(scope);
+    }
+    else {
+        scopeLevels.set(scope, level);
+    }
+}
+export function setScopeRedactions(scope, keys) {
+    scopeRedactions.set(scope, new Set(keys.map((k) => k.toLowerCase())));
+}
+/** Resolve the active level for a scope. Falls through:
+ *    scope -> parent scopes (split by `.`) -> default. */
+export function levelForScope(scope) {
+    const direct = scopeLevels.get(scope);
+    if (direct)
+        return direct;
+    /* Walk parent scopes: "state_channel.client" -> "state_channel". */
+    const parts = scope.split('.');
+    while (parts.length > 1) {
+        parts.pop();
+        const parent = parts.join('.');
+        const got = scopeLevels.get(parent);
+        if (got)
+            return got;
+    }
+    return defaultLevel;
+}
+/** Resolve the redaction set for a scope: union of scope's own +
+ *  every ancestor + GLOBAL_REDACTIONS. */
+export function redactionsForScope(scope) {
+    const out = new Set(GLOBAL_REDACTIONS);
+    const parts = scope.split('.');
+    while (parts.length > 0) {
+        const s = parts.join('.');
+        const r = scopeRedactions.get(s);
+        if (r)
+            for (const k of r)
+                out.add(k);
+        parts.pop();
+    }
+    return out;
+}
+/** Recursively redact keys in an object. Leaves primitives,
+ *  arrays of primitives alone. Cycles bail out. */
+function redactObject(obj, redactions, seen = new WeakSet()) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== 'object')
+        return obj;
+    if (seen.has(obj))
+        return '[CIRCULAR]';
+    seen.add(obj);
+    if (Array.isArray(obj)) {
+        return obj.map((v) => redactObject(v, redactions, seen));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (redactions.has(k.toLowerCase())) {
+            out[k] = '[REDACTED]';
+        }
+        else if (v && typeof v === 'object') {
+            out[k] = redactObject(v, redactions, seen);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/* ----- Built-in sinks ----- */
+export function consoleHumanSink() {
+    return {
+        write(e) {
+            const tag = '[' + e.level.toUpperCase() + ' ' + e.scope + ']';
+            const payload = e.data !== undefined ? ' ' + JSON.stringify(e.data) : '';
+            const reqId = e.request_id ? ' req=' + e.request_id : '';
+            console.log(tag + reqId + ' ' + e.msg + payload);
+        },
+    };
+}
+export function consoleJsonSink() {
+    return {
+        write(e) {
+            console.log(JSON.stringify(e));
+        },
+    };
+}
+/** In-memory ring buffer sink. Useful for tests + for a future
+ *  `yf log capture` bundle (read the buffer + dump). */
+export class RingSink {
+    capacity;
+    buf = [];
+    constructor(capacity = 1000) {
+        this.capacity = capacity;
+    }
+    write(e) {
+        this.buf.push(e);
+        if (this.buf.length > this.capacity)
+            this.buf.shift();
+    }
+    snapshot() {
+        return [...this.buf];
+    }
+    clear() {
+        this.buf = [];
+    }
+}
+/* ----- Active sinks ----- */
+const sinks = [consoleHumanSink()];
+export function addSink(sink) { sinks.push(sink); }
+export function clearSinks() { sinks.length = 0; }
+export function getSinks() { return sinks; }
+function emit(int, level, msg, data) {
+    if (LEVEL_RANK[level] < LEVEL_RANK[levelForScope(int.scope)])
+        return;
+    const redactions = redactionsForScope(int.scope);
+    const safeData = data !== undefined
+        ? redactObject(data, redactions)
+        : undefined;
+    const entry = {
+        ts: new Date().toISOString(),
+        level, scope: int.scope, msg,
+        ...(safeData !== undefined ? { data: safeData } : {}),
+        ...(int.requestId ? { request_id: int.requestId } : {}),
+    };
+    for (const s of sinks) {
+        try {
+            s.write(entry);
+        }
+        catch { /* never let a sink break the producer */ }
+    }
+}
+export function createLogger(scope, opts = {}) {
+    const internal = { scope, ...(opts.request_id ? { requestId: opts.request_id } : {}) };
+    return {
+        scope,
+        isEnabled(level) {
+            return LEVEL_RANK[level] >= LEVEL_RANK[levelForScope(scope)];
+        },
+        trace(m, d) { emit(internal, 'trace', m, d); },
+        debug(m, d) { emit(internal, 'debug', m, d); },
+        info(m, d) { emit(internal, 'info', m, d); },
+        warn(m, d) { emit(internal, 'warn', m, d); },
+        error(m, d) { emit(internal, 'error', m, d); },
+        fatal(m, d) { emit(internal, 'fatal', m, d); },
+        child(o) {
+            const sub = o.subscope ? scope + '.' + o.subscope : scope;
+            return createLogger(sub, o.request_id ? { request_id: o.request_id } : {});
+        },
+    };
+}
+/** Wrap an async function so its duration + outcome are
+ *  emitted at debug level (success) / warn level (failure). */
+export async function withTimingLog(logger, event, fn, context) {
+    const t0 = Date.now();
+    try {
+        const r = await fn();
+        logger.debug(event + '.ok', { ...context, duration_ms: Date.now() - t0 });
+        return r;
+    }
+    catch (err) {
+        logger.warn(event + '.err', {
+            ...context,
+            duration_ms: Date.now() - t0,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/** Test/CLI helper: reset all state. */
+export function resetLoggingForTests() {
+    currentEnv = 'production';
+    defaultLevel = ENV_DEFAULTS.production;
+    scopeLevels.clear();
+    scopeRedactions.clear();
+    sinks.length = 0;
+    sinks.push(consoleHumanSink());
+}
+export function currentEnvironment() { return currentEnv; }
+export function currentDefaultLevel() { return defaultLevel; }
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

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

package/dist/core/mode.d.ts

@@ -0,0 +1,26 @@
+export type ForgeMode = 'didactico' | 'tecnico';
+export declare const FORGE_MODES: readonly ForgeMode[];
+export declare const DEFAULT_MODE: ForgeMode;
+export interface ResolveModeOptions {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** Optional CLI flag value (raw -- we validate). */
+    cliFlag?: string;
+    /** Optional env override (defaults to process.env.YF_MODE). */
+    envValue?: string;
+}
+export interface ResolvedMode {
+    mode: ForgeMode;
+    /** Which precedence layer won. */
+    source: 'env' | 'cli' | 'project' | 'default';
+}
+/** Resolve the effective mode for a process. */
+export declare function resolveMode(opts: ResolveModeOptions): Promise<ResolvedMode>;
+/** Persist `mode` into the project config file, creating it
+ *  if missing. Existing fields are preserved. */
+export declare function persistMode(projectRoot: string, mode: ForgeMode): Promise<void>;
+/** System-prompt suffix that the chat orchestrator injects
+ *  into the Claude system role so the model adapts its tone
+ *  + level of consultation to the user's mode. */
+export declare function modePromptSuffix(mode: ForgeMode): string;
+//# sourceMappingURL=mode.d.ts.map

package/dist/core/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/core/mode.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAChD,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAA6B,CAAC;AAC1E,eAAO,MAAM,YAAY,EAAE,SAAuB,CAAC;AAMnD,MAAM,WAAW,kBAAkB;IACjC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;CAC/C;AAoBD,gDAAgD;AAChD,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAqBjF;AAED;iDACiD;AACjD,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAUrF;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CA+BxD"}