owflow 0.6.0 → 0.7.0

package/dist/configuration/commands-config.js

@@ -1,19 +1,19 @@
-import fs from "node:fs";
-import path from "node:path";
-import matter from "gray-matter";
-import { loadMarkdownDir } from "../utils/file-util.js";
-import { PLUGIN_ROOT } from "../utils/plugin-info.js";
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { loadMarkdownDir } from '../utils/file-util.js';
+import { PLUGIN_ROOT } from '../utils/plugin-info.js';
 // Keeps the rendered body independent of the line endings of this file's storage.
-const CRLF = "\r\n";
-const REQUIRED_COMMAND_KEYS = ["name", "description"];
+const CRLF = '\r\n';
+const REQUIRED_COMMAND_KEYS = ['name', 'description'];
 /**
  * Renders the command body for one skill from its frontmatter.
  * Pure: one frontmatter object in, one string out.
  */
 export const renderCommandTemplate = (data) => [
     `CRITICAL INSTRUCTION: You MUST invoke the ${data.name} skill immediately as your FIRST action.`,
-    "",
-    "Use the Skill tool with these exact parameters:",
+    '',
+    'Use the Skill tool with these exact parameters:',
     `name: "${data.name}"`,
     `prompt: "$ARGUMENTS"`,
 ].join(CRLF);
@@ -24,24 +24,24 @@ export const renderCommandTemplate = (data) => [
  * register silently incomplete.
  */
 export const readSkillFrontmatter = () => {
-    const skillsDir = path.join(PLUGIN_ROOT, "skills");
+    const skillsDir = path.join(PLUGIN_ROOT, 'skills');
     const skills = [];
     for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
-        const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+        const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
         if (!fs.existsSync(skillFile))
             continue;
         skills.push({
             slug: entry.name,
-            data: matter(fs.readFileSync(skillFile, "utf8")).data,
+            data: matter(fs.readFileSync(skillFile, 'utf8')).data,
         });
     }
     return skills;
 };
 export const configureCommands = (config) => {
     config.command = config.command || {};
-    for (const { data, content } of loadMarkdownDir("commands")) {
+    for (const { data, content } of loadMarkdownDir('commands')) {
         const name = data.name;
         if (!name)
             continue;
@@ -54,16 +54,16 @@ export const configureCommands = (config) => {
             ...(data.agent && { agent: data.agent }),
             ...(data.model && { model: data.model }),
             ...(data.subtask !== undefined && {
-                subtask: data.subtask === "true",
+                subtask: data.subtask === 'true',
             }),
         };
     }
     for (const { slug, data } of readSkillFrontmatter()) {
-        if (data["user-invocable"] !== true)
+        if (data['user-invocable'] !== true)
             continue;
-        const missing = REQUIRED_COMMAND_KEYS.filter((key) => typeof data[key] !== "string" || data[key] === "");
+        const missing = REQUIRED_COMMAND_KEYS.filter((key) => typeof data[key] !== 'string' || data[key] === '');
         if (missing.length > 0) {
-            throw new Error(`[owflow] Skill '${slug}' is user-invocable but is missing required frontmatter: ${missing.join(", ")}`);
+            throw new Error(`[owflow] Skill '${slug}' is user-invocable but is missing required frontmatter: ${missing.join(', ')}`);
         }
         const name = data.name;
         // Don't overwrite commands the user has explicitly configured

package/dist/configuration/skills-config.d.ts

@@ -0,0 +1,2 @@
+import type { OpenCodeConfig } from '../types/opencode-types.js';
+export declare const configureSkills: (config: OpenCodeConfig) => void;

package/dist/configuration/skills-config.js

@@ -1,9 +1,9 @@
-import path from "node:path";
-import { PLUGIN_ROOT } from "../utils/plugin-info.js";
+import path from 'node:path';
+import { PLUGIN_ROOT } from '../utils/plugin-info.js';
 export const configureSkills = (config) => {
     config.skills = config.skills || {};
     config.skills.paths = config.skills.paths || [];
-    const skillsDir = path.join(PLUGIN_ROOT, "skills");
+    const skillsDir = path.join(PLUGIN_ROOT, 'skills');
     if (!config.skills.paths.includes(skillsDir)) {
         config.skills.paths.push(skillsDir);
     }

package/dist/hooks/hooks-diagnostics.d.ts

@@ -0,0 +1,3 @@
+import type { HookReportInput, InterpreterResolution } from '../types/hook-types.js';
+export declare const interpreterLabel: (i: InterpreterResolution) => string;
+export declare const renderSnapshot: (input: HookReportInput) => readonly string[];

package/dist/hooks/hooks-diagnostics.js

@@ -0,0 +1,21 @@
+export const interpreterLabel = (i) => `${i.resolved ?? i.expected} (${i.available ? 'available' : 'missing'})`;
+const buildReportRows = (input) => [
+    ...(input.bypassed ? [{ path: '(all hooks)', event: '-', interpreter: '-', status: 'hooks bypassed (OWFLOW_HOOKS_DISABLED=1)' }] : []),
+    ...input.entries.map((e) => ({
+        path: e.path,
+        event: e.event,
+        interpreter: interpreterLabel(e.interpreter),
+        status: e.status === 'registered' ? 'registered' : 'will fail closed at fire',
+    })),
+    ...(input.failures ?? []).map((f) => ({
+        path: f.path,
+        event: '-',
+        interpreter: '-',
+        status: `invalid: ${f.error}`,
+    })),
+];
+export const renderSnapshot = (input) => {
+    const invalid = input.failures?.length ?? 0;
+    const head = `[owflow] hooks: ${input.entries.length} loaded${invalid > 0 ? `, ${invalid} invalid` : ''}`;
+    return [head, ...buildReportRows(input).map((r) => `[owflow]   ${r.path} -> ${r.event} ${r.interpreter} - ${r.status}`)];
+};

package/dist/hooks/hooks-persistence.d.ts

@@ -0,0 +1,17 @@
+import { type HookEventName, type HookLogReadResult, type HookRunLogRecord, type HookStatusReadResult } from '../types/hook-types.js';
+export * from '../types/hook-types.js';
+export declare const STATUS_FILE_ENV = "OWFLOW_HOOKS_STATUS_FILE";
+export declare const LOG_FILE_ENV = "OWFLOW_HOOK_LOGS_FILE";
+export declare const workspaceKey: (workspace: string) => string;
+export declare const getUserTmpDir: () => string;
+export declare const resolveHooksStatusFile: (workspace: string) => string;
+export declare const resolveHooksLogFile: (workspace: string, hookName?: string) => string;
+export declare const resolveHooksLatestSymlink: (workspace: string, targetLogFile?: string) => string;
+export declare const appendWithRotation: (filePath: string, line: string, maxBytes?: number) => void;
+export declare const writeHookCrashLog: (workspace: string, source: string, error: unknown) => void;
+export declare const readHookStatusSnapshot: (file: string) => HookStatusReadResult;
+export declare const MAX_LOG_TAIL_READ_BYTES: number;
+export declare const DEFAULT_MAX_LOG_RECORDS = 500;
+export declare const readHookLogRecords: (file: string, maxRecords?: number) => HookLogReadResult;
+export declare const readSessionLatestLogs: (file: string, sessionID: string) => Map<string, HookRunLogRecord>;
+export declare const readSessionHookLogs: (file: string, event: HookEventName, since?: number, sessionID?: string) => readonly HookRunLogRecord[];

package/dist/hooks/hooks-persistence.js

@@ -0,0 +1,207 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {} from '../types/hook-types.js';
+export * from '../types/hook-types.js';
+export const STATUS_FILE_ENV = 'OWFLOW_HOOKS_STATUS_FILE';
+export const LOG_FILE_ENV = 'OWFLOW_HOOK_LOGS_FILE';
+const DEFAULT_LOG_ROTATION_BYTES = 4 * 1024 * 1024;
+export const workspaceKey = (workspace) => {
+    let resolved = path.resolve(workspace);
+    try {
+        resolved = fs.realpathSync.native(resolved);
+    }
+    catch {
+        // keep resolved path when workspace does not exist yet
+    }
+    return crypto
+        .createHash('sha256')
+        .update(process.platform === 'win32' ? resolved.toLowerCase() : resolved)
+        .digest('hex')
+        .slice(0, 16);
+};
+export const getUserTmpDir = () => {
+    const uid = typeof process.getuid === 'function' ? String(process.getuid()) : (process.env.USER ?? process.env.USERNAME ?? 'default');
+    return path.join(os.tmpdir(), `opencode-${uid}`);
+};
+export const resolveHooksStatusFile = (workspace) => process.env[STATUS_FILE_ENV] ?? path.join(getUserTmpDir(), `owflow-hooks-${workspaceKey(workspace)}.json`);
+const sanitizeHookStem = (hookName) => {
+    if (!hookName)
+        return '';
+    const cleaned = path
+        .basename(hookName)
+        .replace(/[^a-z0-9-]/gi, '-')
+        .replace(/^-+|-+$/g, '');
+    return cleaned.length > 0 ? `-${cleaned}` : '';
+};
+export const resolveHooksLogFile = (workspace, hookName) => process.env[LOG_FILE_ENV] ?? path.join(getUserTmpDir(), `owflow-hook-logs-${workspaceKey(workspace)}${sanitizeHookStem(hookName)}.jsonl`);
+export const resolveHooksLatestSymlink = (workspace, targetLogFile) => {
+    const symlinkPath = path.join(getUserTmpDir(), `owflow-hooks-latest-${workspaceKey(workspace)}.jsonl`);
+    const target = targetLogFile ?? resolveHooksLogFile(workspace);
+    try {
+        fs.mkdirSync(path.dirname(symlinkPath), { recursive: true, mode: 0o700 });
+        try {
+            const stat = fs.lstatSync(symlinkPath);
+            if (stat.isSymbolicLink() || stat.isFile()) {
+                fs.unlinkSync(symlinkPath);
+            }
+        }
+        catch { }
+        fs.symlinkSync(target, symlinkPath);
+    }
+    catch {
+        // Graceful fallback for non-admin Windows or filesystem restrictions
+    }
+    return symlinkPath;
+};
+export const appendWithRotation = (filePath, line, maxBytes = DEFAULT_LOG_ROTATION_BYTES) => {
+    if (!line)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        try {
+            const stat = fs.lstatSync(filePath);
+            if (stat.isSymbolicLink())
+                return;
+            if (stat.size > maxBytes) {
+                try {
+                    const rotStat = fs.lstatSync(`${filePath}.1`);
+                    if (rotStat.isSymbolicLink())
+                        fs.unlinkSync(`${filePath}.1`);
+                }
+                catch { }
+                fs.renameSync(filePath, `${filePath}.1`);
+            }
+        }
+        catch (err) {
+            if (err?.code !== 'ENOENT')
+                return;
+        }
+        const content = line.endsWith('\n') ? line : `${line}\n`;
+        const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | (fs.constants.O_NOFOLLOW ?? 0);
+        const fd = fs.openSync(filePath, flags, 0o600);
+        try {
+            fs.writeFileSync(fd, content, 'utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        // Best-effort log persistence never affects hook execution.
+    }
+};
+export const writeHookCrashLog = (workspace, source, error) => {
+    try {
+        const crashFile = path.join(getUserTmpDir(), 'owflow-hooks-crash.log');
+        const timestamp = new Date().toISOString();
+        const errStr = error instanceof Error ? (error.stack ?? error.message) : String(error);
+        const entry = `[${timestamp}] [${source}] [workspace: ${workspace}]\n${errStr}\n\n`;
+        appendWithRotation(crashFile, entry);
+    }
+    catch {
+        // Best-effort crash logging never throws
+    }
+};
+const statusFileCache = new Map();
+const logRecordsCache = new Map();
+export const readHookStatusSnapshot = (file) => {
+    try {
+        const stat = fs.lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            return { kind: 'invalid' };
+        const cached = statusFileCache.get(file);
+        if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+            return cached.value;
+        }
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed?.version !== 1 || typeof parsed.hooks !== 'object' || parsed.hooks === null) {
+            return { kind: 'invalid' };
+        }
+        const result = { kind: 'ok', snapshot: parsed };
+        statusFileCache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, value: result });
+        return result;
+    }
+    catch (error) {
+        statusFileCache.delete(file);
+        return error?.code === 'ENOENT' ? { kind: 'missing' } : { kind: 'invalid' };
+    }
+};
+export const MAX_LOG_TAIL_READ_BYTES = 256 * 1024;
+export const DEFAULT_MAX_LOG_RECORDS = 500;
+export const readHookLogRecords = (file, maxRecords = DEFAULT_MAX_LOG_RECORDS) => {
+    try {
+        const stat = fs.lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            return { kind: 'invalid' };
+        const cached = logRecordsCache.get(file);
+        if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+            return cached.value;
+        }
+        const startOffset = Math.max(0, stat.size - MAX_LOG_TAIL_READ_BYTES);
+        const readLength = stat.size - startOffset;
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        const buffer = Buffer.alloc(readLength);
+        try {
+            fs.readSync(fd, buffer, 0, readLength, startOffset);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const raw = buffer.toString('utf8');
+        const lines = raw.split('\n');
+        if (startOffset > 0)
+            lines.shift();
+        const records = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                if (rec?.version === 1 && typeof rec.event === 'string' && typeof rec.name === 'string') {
+                    records.push(rec);
+                }
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        const trimmed = records.slice(-maxRecords);
+        const result = { kind: 'ok', records: trimmed, truncated: startOffset > 0 };
+        logRecordsCache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, value: result });
+        return result;
+    }
+    catch (error) {
+        logRecordsCache.delete(file);
+        return error?.code === 'ENOENT' ? { kind: 'missing' } : { kind: 'invalid' };
+    }
+};
+export const readSessionLatestLogs = (file, sessionID) => {
+    const map = new Map();
+    if (!sessionID)
+        return map;
+    const result = readHookLogRecords(file);
+    if (result.kind !== 'ok')
+        return map;
+    for (const record of result.records) {
+        if (record.sessionID === sessionID) {
+            map.set(record.event, record);
+        }
+    }
+    return map;
+};
+export const readSessionHookLogs = (file, event, since = Number.NEGATIVE_INFINITY, sessionID) => {
+    const result = readHookLogRecords(file);
+    if (result.kind !== 'ok')
+        return [];
+    return result.records.filter((r) => {
+        if (r.event !== event)
+            return false;
+        if (sessionID !== undefined && sessionID.length > 0) {
+            if (r.sessionID !== sessionID && r.sessionID !== undefined)
+                return false;
+        }
+        return r.startedAt >= since;
+    });
+};

package/dist/hooks/hooks-registry.d.ts

@@ -0,0 +1,6 @@
+import { HookDigestMode, type HookScan } from '../types/hook-types.js';
+export declare const IGNORED_FILENAMES: Set<string>;
+export declare const scanHooks: (hooksDir: string, options?: {
+    mode?: HookDigestMode;
+    which?: (cmd: string) => string | null;
+}) => HookScan;

package/dist/hooks/hooks-registry.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { EXCLUDED_EVENT_NAMES, HookDigestMode, HOOK_EVENT_NAMES, } from '../types/hook-types.js';
+import { hooksLocationLabel } from '../utils/workflow-paths.js';
+const HOOK_STEM_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const STEM_TO_EVENT = new Map(HOOK_EVENT_NAMES.map((ev) => [ev.replaceAll('.', '-'), ev]));
+const EXCLUDED_STEMS = new Map(EXCLUDED_EVENT_NAMES.map((ev) => [ev.replaceAll('.', '-'), ev]));
+export const IGNORED_FILENAMES = new Set(['.ds_store', 'thumbs.db', 'desktop.ini', '.gitkeep']);
+const isIgnoredFile = (name) => {
+    const lower = name.toLowerCase();
+    return IGNORED_FILENAMES.has(lower) || lower.endsWith('.md') || name.endsWith('~') || name.endsWith('.swp');
+};
+const RECOVERY_HINT = 'Hint: fix or remove the invalid file(s) and restart OpenCode. User hooks are bypassed until the hooks directory validates; the built-in destructive-command guard remains active. To start without user hooks, set OWFLOW_HOOKS_DISABLED=1.';
+export const scanHooks = (hooksDir, options = {}) => {
+    const mode = options.mode ?? HookDigestMode.FailFast;
+    const which = options.which ?? Bun.which;
+    if (!fs.existsSync(hooksDir))
+        return { entries: [], failures: [] };
+    if (!fs.statSync(hooksDir).isDirectory()) {
+        const failures = [{ path: hooksDir, error: `the hooks anchor exists but is not a directory (${hooksLocationLabel})` }];
+        if (mode === HookDigestMode.FailFast)
+            throw new Error(formatFatal(failures));
+        return { entries: [], failures };
+    }
+    const sh = which('bash') ?? undefined;
+    const ps1 = which('pwsh') ?? which('powershell.exe') ?? undefined;
+    const interpreters = {
+        '.sh': { expected: 'bash', available: Boolean(sh), ...(sh ? { resolved: sh } : {}) },
+        '.ps1': { expected: 'pwsh', available: Boolean(ps1), ...(ps1 ? { resolved: ps1 } : {}) },
+    };
+    const entries = [];
+    const failures = [];
+    const seenStems = new Map();
+    for (const dirent of fs.readdirSync(hooksDir, { withFileTypes: true })) {
+        if (isIgnoredFile(dirent.name))
+            continue;
+        const entryPath = path.join(hooksDir, dirent.name);
+        if (!dirent.isFile()) {
+            failures.push({ path: entryPath, error: `not a regular file (only hook scripts belong in ${hooksLocationLabel}/)` });
+            continue;
+        }
+        const ext = path.extname(dirent.name);
+        if (ext !== '.sh' && ext !== '.ps1') {
+            failures.push({ path: entryPath, error: `extension "${ext || '(none)'}" is not routable (expected .sh or .ps1)` });
+            continue;
+        }
+        const stem = dirent.name.slice(0, -ext.length);
+        if (!HOOK_STEM_PATTERN.test(stem)) {
+            failures.push({ path: entryPath, error: `stem "${stem}" is not lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)` });
+            continue;
+        }
+        const excluded = EXCLUDED_STEMS.get(stem);
+        if (excluded) {
+            failures.push({ path: entryPath, error: `stem "${stem}" derives to "${excluded}", an excluded event that cannot be hooked` });
+            continue;
+        }
+        const event = STEM_TO_EVENT.get(stem);
+        if (!event) {
+            failures.push({
+                path: entryPath,
+                error: `stem "${stem}" derives to "${stem.replaceAll('-', '.')}", which is not a dispatchable hook or a known host event`,
+            });
+            continue;
+        }
+        const interpreter = interpreters[ext];
+        const entry = {
+            path: entryPath,
+            event,
+            interpreter,
+            status: interpreter.available ? 'registered' : 'will-fail-closed',
+        };
+        const existing = seenStems.get(stem);
+        if (existing) {
+            const names = `${path.basename(existing.path)}, ${path.basename(entryPath)}`;
+            failures.push({
+                path: entryPath,
+                error: `hook name "${stem}" is provided by multiple files (${names}); define it in exactly one format`,
+            });
+            const existingIdx = entries.findIndex((e) => e.path === existing.path);
+            if (existingIdx !== -1) {
+                entries.splice(existingIdx, 1);
+                failures.push({
+                    path: existing.path,
+                    error: `hook name "${stem}" is provided by multiple files (${names}); define it in exactly one format`,
+                });
+            }
+        }
+        else {
+            seenStems.set(stem, entry);
+            entries.push(entry);
+        }
+    }
+    entries.sort((a, b) => (a.event < b.event ? -1 : a.event > b.event ? 1 : 0));
+    failures.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    if (mode === HookDigestMode.FailFast && failures.length > 0) {
+        throw new Error(formatFatal(failures));
+    }
+    return { entries, failures };
+};
+const formatFatal = (failures) => {
+    const count = failures.length === 1 ? '1 invalid entry' : `${failures.length} invalid entries`;
+    const rows = failures.map((f) => `  - ${f.path}: ${f.error}`).join('\n');
+    return `[owflow] ${count} in ${hooksLocationLabel}/\n${rows}\n${RECOVERY_HINT}`;
+};

package/dist/hooks/hooks-wrapper.d.ts

@@ -0,0 +1,25 @@
+import type { Hooks } from '@opencode-ai/plugin';
+import { type HookEventName, type HookScan, type HooksWrapperOptions } from '../types/hook-types.js';
+export { CircuitBreakerTracker, type CircuitBreakerEntry } from './runtime/circuit-breaker.js';
+export { SessionAbortController, buildCircuitBreakerError, buildInterpreterUnavailableError, buildSpawnError, buildProcessFailureError, } from './runtime/failure-policy.js';
+export { HookSpawnError, executeHookProcess } from './runtime/process-executor.js';
+export { NON_SESSION_STREAM_CAP_BYTES, StatusRecorder } from './runtime/status-recorder.js';
+declare class HooksWrapper {
+    private PASSTHROUGH_EVENTS;
+    private IDENTITY_KEYS;
+    snapshot: HookScan;
+    private statusRecorder;
+    private abortController;
+    private circuitBreaker;
+    private activeProcs;
+    private directory;
+    private runCounter;
+    constructor(directory: string, endSession?: (sessionID: string) => Promise<void> | void, options?: HooksWrapperOptions);
+    private sessionIDFrom;
+    private buildStdinPayload;
+    dispose: () => void;
+    dispatch: (event: HookEventName, input?: unknown, output?: Record<string, unknown>) => Promise<void>;
+    createDispatchHandlers: () => Hooks;
+}
+export { HooksWrapper };
+export default HooksWrapper;