@ashlr/hub 2.2.0

package/dist/core/plugins/wrappers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * core/plugins/wrappers.ts — M33 plugin contribution safety wrappers.
+ *
+ * CONTRACT RULES (non-negotiable):
+ *  - wrapScanner: 15s AbortSignal timeout, never-throws (→ []), cap 100 items,
+ *    clamp value/effort to 1..5 integers, recompute score via scoreItem,
+ *    scrub title+detail with scrubSecrets, force source:'plugin', tags include
+ *    ['plugin', pluginName, s.id], ids namespaced plugin:<name>:<s.id>:<orig|index>.
+ *  - validateTemplate: id prefixed <pluginName>: unless already, reject any
+ *    template file path that is absolute, contains '..', or starts with '.git/'.
+ *    Returns validated template or null (audited on rejection).
+ *  - wrapCommand: run wrapped with audit of invocation + exit code, catches
+ *    throws → exit 1.
+ *  - All wrappers NEVER throw themselves.
+ */
+import type { WorkItem, ProjectTemplate } from '../types.js';
+import type { PluginScanner, PluginCommandSpec } from './types.js';
+/**
+ * Wrap a PluginScanner for safety:
+ *  - 15-second AbortSignal timeout (signal passed to scanner.scan).
+ *  - Never throws → [] on any error or timeout.
+ *  - Caps results at 100 items.
+ *  - Clamps value/effort to integers in 1..5.
+ *  - Recomputes score via scoreItem.
+ *  - Scrubs title + detail with scrubSecrets.
+ *  - Forces source: 'plugin'.
+ *  - Forces tags to include ['plugin', pluginName, s.id].
+ *  - Namespaces id as "plugin:<name>:<s.id>:<orig-id-or-index>".
+ */
+export declare function wrapScanner(pluginName: string, s: PluginScanner): (repo: string) => Promise<WorkItem[]>;
+export declare function validateTemplate(pluginName: string, t: ProjectTemplate): ProjectTemplate | null;
+/**
+ * Wrap a PluginCommandSpec for safety:
+ *  - Audits invocation (action: "plugin:<name>:command:<cmd.name>").
+ *  - Catches throws → returns exit code 1.
+ *  - Audits the exit code (ok when 0, error otherwise).
+ *
+ * NEVER throws from the wrapper itself.
+ */
+export declare function wrapCommand(pluginName: string, c: PluginCommandSpec): PluginCommandSpec;

package/dist/core/plugins/wrappers.js

@@ -0,0 +1,229 @@
+/**
+ * core/plugins/wrappers.ts — M33 plugin contribution safety wrappers.
+ *
+ * CONTRACT RULES (non-negotiable):
+ *  - wrapScanner: 15s AbortSignal timeout, never-throws (→ []), cap 100 items,
+ *    clamp value/effort to 1..5 integers, recompute score via scoreItem,
+ *    scrub title+detail with scrubSecrets, force source:'plugin', tags include
+ *    ['plugin', pluginName, s.id], ids namespaced plugin:<name>:<s.id>:<orig|index>.
+ *  - validateTemplate: id prefixed <pluginName>: unless already, reject any
+ *    template file path that is absolute, contains '..', or starts with '.git/'.
+ *    Returns validated template or null (audited on rejection).
+ *  - wrapCommand: run wrapped with audit of invocation + exit code, catches
+ *    throws → exit 1.
+ *  - All wrappers NEVER throw themselves.
+ */
+import { audit } from '../sandbox/audit.js';
+import { scoreItem } from '../portfolio/backlog.js';
+import { scrubSecrets } from '../knowledge/index.js';
+// ---------------------------------------------------------------------------
+// wrapScanner
+// ---------------------------------------------------------------------------
+/** Maximum items returned by a plugin scanner. */
+const SCANNER_CAP = 100;
+/** Scanner timeout in milliseconds. */
+const SCANNER_TIMEOUT_MS = 15_000;
+/**
+ * Wrap a PluginScanner for safety:
+ *  - 15-second AbortSignal timeout (signal passed to scanner.scan).
+ *  - Never throws → [] on any error or timeout.
+ *  - Caps results at 100 items.
+ *  - Clamps value/effort to integers in 1..5.
+ *  - Recomputes score via scoreItem.
+ *  - Scrubs title + detail with scrubSecrets.
+ *  - Forces source: 'plugin'.
+ *  - Forces tags to include ['plugin', pluginName, s.id].
+ *  - Namespaces id as "plugin:<name>:<s.id>:<orig-id-or-index>".
+ */
+export function wrapScanner(pluginName, s) {
+    return async (repo) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), SCANNER_TIMEOUT_MS);
+        let raw;
+        try {
+            raw = await s.scan(repo, { signal: controller.signal });
+        }
+        catch {
+            // never-throws contract: scanner timeout or error → []
+            return [];
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!Array.isArray(raw))
+            return [];
+        const result = [];
+        const capped = raw.slice(0, SCANNER_CAP);
+        for (let i = 0; i < capped.length; i++) {
+            const item = capped[i];
+            if (item === null || typeof item !== 'object')
+                continue;
+            // Clamp value/effort to integers in 1..5
+            const rawValue = typeof item.value === 'number' ? item.value : 3;
+            const rawEffort = typeof item.effort === 'number' ? item.effort : 2;
+            const value = Math.max(1, Math.min(5, Math.round(rawValue)));
+            const effort = Math.max(1, Math.min(5, Math.round(rawEffort)));
+            // Recompute score via scoreItem (deterministic, pure)
+            const score = scoreItem(value, effort);
+            // Scrub secrets from title + detail
+            const rawTitle = typeof item.title === 'string' ? item.title : '';
+            const rawDetail = typeof item.detail === 'string' ? item.detail : '';
+            const title = scrubSecrets(rawTitle);
+            const detail = scrubSecrets(rawDetail);
+            // Namespace id: plugin:<name>:<s.id>:<orig-or-index>
+            const origId = typeof item.id === 'string' && item.id.length > 0 ? item.id : String(i);
+            const id = `plugin:${pluginName}:${s.id}:${origId}`;
+            // Force tags to include ['plugin', pluginName, s.id]
+            const baseTags = Array.isArray(item.tags)
+                ? item.tags.filter((t) => typeof t === 'string')
+                : [];
+            const requiredTags = ['plugin', pluginName, s.id];
+            const tags = [
+                ...requiredTags,
+                ...baseTags.filter((t) => !requiredTags.includes(t)),
+            ];
+            const wrapped = {
+                id,
+                repo: typeof item.repo === 'string' ? item.repo : repo,
+                source: 'plugin',
+                title,
+                detail,
+                value,
+                effort,
+                score,
+                tags,
+                ts: typeof item.ts === 'string' ? item.ts : new Date().toISOString(),
+            };
+            result.push(wrapped);
+        }
+        return result;
+    };
+}
+// ---------------------------------------------------------------------------
+// validateTemplate
+// ---------------------------------------------------------------------------
+/**
+ * Validate and sanitize a plugin-contributed template.
+ *
+ * - Prefixes id with "<pluginName>:" unless it already starts with that prefix.
+ * - Rejects any template whose files() function (called with probe ctx) returns
+ *   a path that is absolute, contains '..', or starts with '.git/'.
+ * - The files() function is wrapped: the path guard also runs on every future
+ *   call so a template cannot sneak bad paths in via a closure.
+ * - Returns the sanitized template or null (rejection is audited).
+ *
+ * NEVER throws.
+ */
+function checkFilePath(pluginName, templateId, p) {
+    if (p.startsWith('/')) {
+        return `plugin "${pluginName}" template "${templateId}" rejected: absolute path "${p}"`;
+    }
+    if (p.includes('..')) {
+        return `plugin "${pluginName}" template "${templateId}" rejected: traversal path "${p}"`;
+    }
+    if (p.startsWith('.git/')) {
+        return `plugin "${pluginName}" template "${templateId}" rejected: .git path "${p}"`;
+    }
+    return null;
+}
+export function validateTemplate(pluginName, t) {
+    try {
+        const prefix = `${pluginName}:`;
+        // Probe the files function with empty-string ctx to catch static bad paths.
+        let probeFiles;
+        try {
+            probeFiles = t.files({ name: '', category: '' });
+        }
+        catch {
+            // files() threw on probe — reject.
+            audit({
+                action: `plugin:${pluginName}:template-rejected`,
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${pluginName}" template "${t.id}" rejected: files() threw on probe`,
+                result: 'refused',
+            });
+            return null;
+        }
+        for (const f of probeFiles) {
+            const reason = checkFilePath(pluginName, t.id, f.path);
+            if (reason !== null) {
+                audit({
+                    action: `plugin:${pluginName}:template-rejected`,
+                    repo: null,
+                    sandboxId: null,
+                    summary: reason,
+                    result: 'refused',
+                });
+                return null;
+            }
+        }
+        // Prefix id if not already prefixed.
+        const id = t.id.startsWith(prefix) ? t.id : `${prefix}${t.id}`;
+        // Wrap files() to enforce path guard on every call.
+        const safeFiles = (ctx) => {
+            let result;
+            try {
+                result = t.files(ctx);
+            }
+            catch {
+                return [];
+            }
+            return result.filter((f) => checkFilePath(pluginName, id, f.path) === null);
+        };
+        return { ...t, id, files: safeFiles };
+    }
+    catch {
+        // Belt-and-suspenders: validateTemplate must never throw.
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// wrapCommand
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a PluginCommandSpec for safety:
+ *  - Audits invocation (action: "plugin:<name>:command:<cmd.name>").
+ *  - Catches throws → returns exit code 1.
+ *  - Audits the exit code (ok when 0, error otherwise).
+ *
+ * NEVER throws from the wrapper itself.
+ */
+export function wrapCommand(pluginName, c) {
+    return {
+        ...c,
+        async run(args, host) {
+            audit({
+                action: `plugin:${pluginName}:command:${c.name}`,
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${pluginName}" command "${c.name}" invoked (${args.length} arg(s))`,
+                result: 'ok',
+            });
+            let exitCode;
+            try {
+                exitCode = await c.run(args, host);
+            }
+            catch (err) {
+                audit({
+                    action: `plugin:${pluginName}:command:${c.name}:exit`,
+                    repo: null,
+                    sandboxId: null,
+                    summary: `plugin "${pluginName}" command "${c.name}" threw: ${err instanceof Error ? err.message : String(err)}`,
+                    result: 'error',
+                });
+                return 1;
+            }
+            const code = typeof exitCode === 'number' && Number.isFinite(exitCode) ? exitCode : 1;
+            audit({
+                action: `plugin:${pluginName}:command:${c.name}:exit`,
+                repo: null,
+                sandboxId: null,
+                summary: `plugin "${pluginName}" command "${c.name}" exited with code ${code}`,
+                result: code === 0 ? 'ok' : 'error',
+            });
+            return code;
+        },
+    };
+}
+//# sourceMappingURL=wrappers.js.map

package/dist/core/plugins/wrappers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers.js","sourceRoot":"","sources":["../../../src/core/plugins/wrappers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAIrD,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,kDAAkD;AAClD,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,uCAAuC;AACvC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,UAAkB,EAClB,CAAgB;IAEhB,OAAO,KAAK,EAAE,IAAY,EAAuB,EAAE;QACjD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,kBAAkB,CAAC,CAAC;QAEvE,IAAI,GAAe,CAAC;QACpB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,uDAAuD;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAEnC,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QAEzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACvB,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAExD,yCAAyC;YACzC,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACjE,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAE/D,sDAAsD;YACtD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAEvC,oCAAoC;YACpC,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YAClE,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;YAEvC,qDAAqD;YACrD,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvF,MAAM,EAAE,GAAG,UAAU,UAAU,IAAI,CAAC,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC;YAEpD,qDAAqD;YACrD,MAAM,QAAQ,GAAa,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;gBACjD,CAAC,CAAE,IAAI,CAAC,IAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;gBAC5E,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;YAClD,MAAM,IAAI,GAAG;gBACX,GAAG,YAAY;gBACf,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;aACrD,CAAC;YAEF,MAAM,OAAO,GAAa;gBACxB,EAAE;gBACF,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;gBACtD,MAAM,EAAE,QAAQ;gBAChB,KAAK;gBACL,MAAM;gBACN,KAAK;gBACL,MAAM;gBACN,KAAK;gBACL,IAAI;gBACJ,EAAE,EAAE,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACrE,CAAC;YAEF,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAS,aAAa,CACpB,UAAkB,EAClB,UAAkB,EAClB,CAAS;IAET,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,WAAW,UAAU,eAAe,UAAU,8BAA8B,CAAC,GAAG,CAAC;IAC1F,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,WAAW,UAAU,eAAe,UAAU,+BAA+B,CAAC,GAAG,CAAC;IAC3F,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1B,OAAO,WAAW,UAAU,eAAe,UAAU,0BAA0B,CAAC,GAAG,CAAC;IACtF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,UAAkB,EAClB,CAAkB;IAElB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG,CAAC;QAEhC,4EAA4E;QAC5E,IAAI,UAA0B,CAAC;QAC/B,IAAI,CAAC;YACH,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;YACnC,KAAK,CAAC;gBACJ,MAAM,EAAE,UAAU,UAAU,oBAAoB;gBAChD,IAAI,EAAE,IAAI;gBACV,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,WAAW,UAAU,eAAe,CAAC,CAAC,EAAE,oCAAoC;gBACrF,MAAM,EAAE,SAAS;aAClB,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACvD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,KAAK,CAAC;oBACJ,MAAM,EAAE,UAAU,UAAU,oBAAoB;oBAChD,IAAI,EAAE,IAAI;oBACV,SAAS,EAAE,IAAI;oBACf,OAAO,EAAE,MAAM;oBACf,MAAM,EAAE,SAAS;iBAClB,CAAC,CAAC;gBACH,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,qCAAqC;QACrC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC;QAE/D,oDAAoD;QACpD,MAAM,SAAS,GAAG,CAAC,GAAuC,EAAkB,EAAE;YAC5E,IAAI,MAAsB,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QAC9E,CAAC,CAAC;QAEF,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,CAAoB;IAClE,OAAO;QACL,GAAG,CAAC;QACJ,KAAK,CAAC,GAAG,CAAC,IAAc,EAAE,IAAgB;YACxC,KAAK,CAAC;gBACJ,MAAM,EAAE,UAAU,UAAU,YAAY,CAAC,CAAC,IAAI,EAAE;gBAChD,IAAI,EAAE,IAAI;gBACV,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,WAAW,UAAU,cAAc,CAAC,CAAC,IAAI,cAAc,IAAI,CAAC,MAAM,UAAU;gBACrF,MAAM,EAAE,IAAI;aACb,CAAC,CAAC;YAEH,IAAI,QAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,QAAQ,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,KAAK,CAAC;oBACJ,MAAM,EAAE,UAAU,UAAU,YAAY,CAAC,CAAC,IAAI,OAAO;oBACrD,IAAI,EAAE,IAAI;oBACV,SAAS,EAAE,IAAI;oBACf,OAAO,EAAE,WAAW,UAAU,cAAc,CAAC,CAAC,IAAI,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;oBAChH,MAAM,EAAE,OAAO;iBAChB,CAAC,CAAC;gBACH,OAAO,CAAC,CAAC;YACX,CAAC;YAED,MAAM,IAAI,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACtF,KAAK,CAAC;gBACJ,MAAM,EAAE,UAAU,UAAU,YAAY,CAAC,CAAC,IAAI,OAAO;gBACrD,IAAI,EAAE,IAAI;gBACV,SAAS,EAAE,IAAI;gBACf,OAAO,EAAE,WAAW,UAAU,cAAc,CAAC,CAAC,IAAI,sBAAsB,IAAI,EAAE;gBAC9E,MAAM,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;aACpC,CAAC,CAAC;YAEH,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/portfolio/backlog.d.ts

@@ -0,0 +1,40 @@
+/**
+ * backlog.ts — Aggregated work-discovery backlog for enrolled repos.
+ *
+ * GUARDRAILS:
+ *  - READ-ONLY: this module never writes to any scanned repo.
+ *  - ENROLLMENT-SCOPED: only listEnrolled() repos are scanned (DEFAULT EMPTY).
+ *  - Never throws: all errors are caught and produce empty/null results.
+ *  - No secrets in persisted data (enforced by scanners + audit).
+ *  - Persists atomically to ~/.ashlr/backlog.json.
+ */
+import type { Backlog } from '../types.js';
+/**
+ * Absolute path of the persisted backlog file: ~/.ashlr/backlog.json.
+ * Re-resolved at call time so tests can relocate HOME.
+ */
+export declare function backlogPath(): string;
+/**
+ * Priority score; higher = do first.
+ * Heuristic: value / effort (effort clamped >= 1; both clamped to 1..5).
+ * Deterministic, pure.
+ */
+export declare function scoreItem(value: number, effort: number): number;
+/**
+ * Load the persisted backlog from ~/.ashlr/backlog.json.
+ * Returns null if the file is absent or unreadable/malformed.
+ * Never throws.
+ */
+export declare function loadBacklog(): Backlog | null;
+/**
+ * Run all SCANNERS over each enrolled repo, aggregate, dedupe, score, persist,
+ * and return the Backlog.
+ *
+ * - Default repos = listEnrolled() (DEFAULT EMPTY => items: []).
+ * - Bounded concurrency: repos scanned sequentially; scanners within a repo
+ *   run in parallel (each scanner is individually bounded + never throws).
+ * - Never throws: any scanner error yields [] (enforced by scanner contract).
+ */
+export declare function buildBacklog(opts?: {
+    repos?: string[];
+}): Promise<Backlog>;

package/dist/core/portfolio/backlog.js

@@ -0,0 +1,177 @@
+/**
+ * backlog.ts — Aggregated work-discovery backlog for enrolled repos.
+ *
+ * GUARDRAILS:
+ *  - READ-ONLY: this module never writes to any scanned repo.
+ *  - ENROLLMENT-SCOPED: only listEnrolled() repos are scanned (DEFAULT EMPTY).
+ *  - Never throws: all errors are caught and produce empty/null results.
+ *  - No secrets in persisted data (enforced by scanners + audit).
+ *  - Persists atomically to ~/.ashlr/backlog.json.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { listEnrolled } from '../sandbox/policy.js';
+import { audit } from '../sandbox/audit.js';
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path of the persisted backlog file: ~/.ashlr/backlog.json.
+ * Re-resolved at call time so tests can relocate HOME.
+ */
+export function backlogPath() {
+    return join(homedir(), '.ashlr', 'backlog.json');
+}
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+/**
+ * Priority score; higher = do first.
+ * Heuristic: value / effort (effort clamped >= 1; both clamped to 1..5).
+ * Deterministic, pure.
+ */
+export function scoreItem(value, effort) {
+    const v = Math.max(1, Math.min(5, value));
+    const e = Math.max(1, Math.min(5, effort));
+    return v / e;
+}
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+/**
+ * Load the persisted backlog from ~/.ashlr/backlog.json.
+ * Returns null if the file is absent or unreadable/malformed.
+ * Never throws.
+ */
+export function loadBacklog() {
+    try {
+        const p = backlogPath();
+        if (!existsSync(p))
+            return null;
+        const raw = readFileSync(p, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed) &&
+            typeof parsed['generatedAt'] === 'string' &&
+            Array.isArray(parsed['repos']) &&
+            Array.isArray(parsed['items'])) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the backlog atomically (write + sync approach for node builtins). */
+function persistBacklog(backlog) {
+    const p = backlogPath();
+    const dir = join(homedir(), '.ashlr');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Atomic write: write to a temp file then rename. Node's fs.renameSync is
+    // atomic on POSIX within the same filesystem.
+    const tmp = p + '.tmp';
+    writeFileSync(tmp, JSON.stringify(backlog, null, 2) + '\n', 'utf8');
+    // Atomic rename: node:fs renameSync is atomic on POSIX within one filesystem.
+    renameSync(tmp, p);
+}
+// ---------------------------------------------------------------------------
+// Deduplication helpers
+// ---------------------------------------------------------------------------
+function dedupeItems(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (!seen.has(item.id)) {
+            seen.add(item.id);
+            out.push(item);
+        }
+    }
+    return out;
+}
+async function getScanners() {
+    let builtin = [];
+    try {
+        const mod = await import('./scanners.js');
+        builtin = mod.SCANNERS;
+    }
+    catch {
+        builtin = [];
+    }
+    // M33: merge enabled-plugin scanners (already wrapped: bounded, never-throw,
+    // scrubbed, namespaced). Best-effort — a broken plugin layer never blocks
+    // the builtin sweep; with plugins.enabled [] this resolves to [].
+    let fromPlugins = [];
+    try {
+        const { loadConfig } = await import('../config.js');
+        const { getPluginScanners } = await import('../plugins/registry.js');
+        fromPlugins = await getPluginScanners(loadConfig());
+    }
+    catch {
+        fromPlugins = [];
+    }
+    return [...builtin, ...fromPlugins];
+}
+/**
+ * Run all SCANNERS over each enrolled repo, aggregate, dedupe, score, persist,
+ * and return the Backlog.
+ *
+ * - Default repos = listEnrolled() (DEFAULT EMPTY => items: []).
+ * - Bounded concurrency: repos scanned sequentially; scanners within a repo
+ *   run in parallel (each scanner is individually bounded + never throws).
+ * - Never throws: any scanner error yields [] (enforced by scanner contract).
+ */
+export async function buildBacklog(opts) {
+    const repos = opts?.repos ?? listEnrolled();
+    const scanners = await getScanners();
+    const now = new Date().toISOString();
+    const allItems = [];
+    // Repos scanned sequentially to avoid thundering-herd on gh/npm APIs.
+    for (const repo of repos) {
+        // Scanners within each repo run in parallel; each is bounded + never throws.
+        const perScannerResults = await Promise.all(scanners.map(async (scanner) => {
+            try {
+                return await scanner(repo);
+            }
+            catch {
+                // Belt-and-suspenders: scanners must not throw, but we catch anyway.
+                return [];
+            }
+        }));
+        for (const items of perScannerResults) {
+            allItems.push(...items);
+        }
+    }
+    // Dedupe by id, recompute score, sort descending.
+    const deduped = dedupeItems(allItems).map((item) => ({
+        ...item,
+        score: scoreItem(item.value, item.effort),
+    }));
+    deduped.sort((a, b) => b.score - a.score);
+    const backlog = {
+        generatedAt: now,
+        repos,
+        items: deduped,
+    };
+    // Persist; never throw on persistence failure.
+    try {
+        persistBacklog(backlog);
+    }
+    catch {
+        // Persistence failure does not prevent returning the in-memory backlog.
+    }
+    // Audit record (metadata only; never secrets).
+    audit({
+        action: 'backlog:refresh',
+        repo: null,
+        sandboxId: null,
+        summary: `backlog refreshed: ${repos.length} repo(s), ${deduped.length} item(s)`,
+        result: 'ok',
+    });
+    return backlog;
+}
+//# sourceMappingURL=backlog.js.map

package/dist/core/portfolio/backlog.js.map

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

package/dist/core/portfolio/scanners.d.ts

@@ -0,0 +1,21 @@
+/**
+ * portfolio/scanners.ts — Work-discovery scanners for `ashlr backlog`.
+ *
+ * GUARDRAILS (enforced throughout this file):
+ *  - READ-ONLY: no file writes, no git mutations, no installs, no fixes,
+ *    no `npm test`/`npm run build`.
+ *  - No shell: all child-process invocations use execFile with arg arrays
+ *    (no shell:true, no string interpolation of repo paths into a shell string).
+ *  - Bounded: skip node_modules/.git/dist/build; cap output/files/time.
+ *  - Never throws: every scanner returns [] on any error/timeout/missing-tool.
+ *  - Enrollment-scoped: callers (buildBacklog) only pass listEnrolled() paths.
+ *  - No secrets in any emitted WorkItem.
+ */
+import type { WorkItem } from '../types.js';
+export declare function scanIssues(repo: string): Promise<WorkItem[]>;
+export declare function scanTodos(repo: string): Promise<WorkItem[]>;
+export declare function scanTests(repo: string): Promise<WorkItem[]>;
+export declare function scanDeps(repo: string): Promise<WorkItem[]>;
+export declare function scanDocs(repo: string): Promise<WorkItem[]>;
+export declare function scanSecurity(repo: string): Promise<WorkItem[]>;
+export declare const SCANNERS: ReadonlyArray<(repo: string) => Promise<WorkItem[]>>;