super-backlog 0.3.1

package/dist/lib/hooks.js

@@ -0,0 +1,78 @@
+// src/lib/hooks.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const GUARD_MARKER = 'super-backlog guard';
+export const REFRESH_MARKER = 'super-backlog dashboard-refresh';
+function markerBlockRe(marker) {
+    return new RegExp(`^# >>> ${marker} [\\d.]+ >>>[\\s\\S]*?# <<< ${marker} <<<\\n?`, 'm');
+}
+export const GUARD_RE = markerBlockRe(GUARD_MARKER);
+export const REFRESH_RE = markerBlockRe(REFRESH_MARKER);
+function hookTemplate(file) {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/lib at runtime, src/lib under vitest
+    const candidates = [join(here, '..', 'templates', file), join(here, 'templates', file)];
+    for (const c of candidates)
+        if (existsSync(c))
+            return readFileSync(c, 'utf8');
+    throw new Error(`${file} template not found`);
+}
+function renderBlock(templateFile, version) {
+    return hookTemplate(templateFile).replace('{{VERSION}}', version);
+}
+/**
+ * Shared marker-block installer: swaps this kind's own block in place when
+ * present, otherwise appends after the current contents (a fresh hook file
+ * gets `#!/bin/sh` + block). Foreign content - including other super-backlog
+ * blocks - is always preserved.
+ */
+function installBlock(gitDir, hookName, re, block) {
+    const path = join(gitDir, 'hooks', hookName);
+    let next;
+    if (existsSync(path)) {
+        const cur = readFileSync(path, 'utf8');
+        next = re.test(cur) ? cur.replace(re, block) : cur.replace(/\n?$/, '\n') + block;
+    }
+    else {
+        next = '#!/bin/sh\n' + block;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+    try {
+        chmodSync(path, 0o755);
+    }
+    catch { /* best effort on Windows */ }
+}
+/** Shared marker-block remover: strips the own block; deletes the file when nothing but a shebang remains. */
+function removeBlock(gitDir, hookName, re) {
+    const path = join(gitDir, 'hooks', hookName);
+    if (!existsSync(path))
+        return false;
+    const cur = readFileSync(path, 'utf8');
+    if (!re.test(cur))
+        return false;
+    const rest = cur.replace(re, '').trim();
+    if (rest === '' || rest === '#!/bin/sh')
+        rmSync(path);
+    else
+        writeFileSync(path, rest + '\n');
+    return true;
+}
+export function renderGuardHook(version) {
+    return renderBlock('guard-hook.sh', version);
+}
+export function installGuardHook(gitDir, version) {
+    installBlock(gitDir, 'pre-commit', GUARD_RE, renderGuardHook(version));
+}
+export function removeGuardHook(gitDir) {
+    return removeBlock(gitDir, 'pre-commit', GUARD_RE);
+}
+export function renderRefreshHook(version) {
+    return renderBlock('dashboard-refresh-hook.sh', version);
+}
+export function installRefreshHook(gitDir, version) {
+    installBlock(gitDir, 'post-commit', REFRESH_RE, renderRefreshHook(version));
+}
+export function removeRefreshHook(gitDir) {
+    return removeBlock(gitDir, 'post-commit', REFRESH_RE);
+}

package/dist/lib/markers.js

@@ -0,0 +1,41 @@
+// src/lib/markers.ts
+const START_RE = /<!--\s*SUPER-BACKLOG:(\d+\.\d+\.\d+)\s*START\s*-->/;
+export function markerStart(version) {
+    return `<!-- SUPER-BACKLOG:${version} START -->`;
+}
+export const MARKER_END = '<!-- SUPER-BACKLOG END -->';
+function ownedSpan(content) {
+    const m = START_RE.exec(content);
+    if (!m || m.index === -1)
+        return null;
+    const start = m.index;
+    const endIdx = content.indexOf(MARKER_END, start);
+    if (endIdx === -1)
+        return null;
+    return { start, end: endIdx + MARKER_END.length };
+}
+export function injectBlock(content, version, block) {
+    const fresh = `${markerStart(version)}\n${block}\n${MARKER_END}`;
+    const span = ownedSpan(content);
+    if (!span) {
+        const sep = content.length === 0 ? '' : content.endsWith('\n') ? '' : '\n';
+        return { content: content + sep + fresh + '\n', action: 'created' };
+    }
+    const existing = content.slice(span.start, span.end);
+    if (existing === fresh)
+        return { content, action: 'unchanged' };
+    return {
+        content: content.slice(0, span.start) + fresh + content.slice(span.end),
+        action: 'replaced',
+    };
+}
+export function stripOwned(content) {
+    const span = ownedSpan(content);
+    if (!span)
+        return { content, removed: false };
+    const before = content.slice(0, span.start);
+    let after = content.slice(span.end);
+    if (before.endsWith('\n') && after.startsWith('\n'))
+        after = after.slice(1);
+    return { content: before + after, removed: true };
+}

package/dist/lib/opencode.js

@@ -0,0 +1,17 @@
+import { OwnershipError } from './ownership.js';
+export const PLUGIN_SPEC = 'superpowers@git+https://github.com/obra/superpowers.git';
+export function applyPluginEntry(config) {
+    const base = config && typeof config === 'object' && !Array.isArray(config)
+        ? { ...config }
+        : {};
+    const raw = base.plugin;
+    const list = Array.isArray(raw) ? [...raw] : raw === undefined ? [] : [raw];
+    if (list.includes(PLUGIN_SPEC))
+        return { config: base, changed: false };
+    const suspicious = list.find((e) => typeof e === 'string' && e.startsWith('superpowers@'));
+    if (suspicious !== undefined) {
+        throw new OwnershipError(`refusing to modify existing superpowers plugin entry "${String(suspicious)}" — resolve manually, then re-run`);
+    }
+    list.push(PLUGIN_SPEC);
+    return { config: { ...base, plugin: list }, changed: true };
+}

package/dist/lib/ownership.js

@@ -0,0 +1,15 @@
+export class OwnershipError extends Error {
+}
+export const FINGERPRINT_RE = /<!--\s*managed-by:\s*super-backlog\s*v?\d+\.\d+\.\d+\s*-->/;
+export function renderSkill(templateContent, version) {
+    const line = `<!-- managed-by: super-backlog ${version} -->`;
+    if (/^---\r?\n/.test(templateContent)) {
+        const close = templateContent.indexOf('\n---', 3);
+        const insertAt = templateContent.indexOf('\n', close + 1) + 1;
+        return (templateContent.slice(0, insertAt) + `\n${line}` + templateContent.slice(insertAt));
+    }
+    return `${line}\n${templateContent}`;
+}
+export function isOwnedSkillFile(content) {
+    return FINGERPRINT_RE.test(content);
+}

package/dist/lib/pkgjson.js

@@ -0,0 +1,41 @@
+// src/lib/pkgjson.ts
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const WANTED_SCRIPTS = {
+    tasks: 'backlog task list',
+    board: 'backlog board',
+    browser: 'backlog browser',
+    dashboard: 'super-backlog dashboard',
+};
+export const WANTED_DEVS = {
+    'backlog.md': 'latest',
+    'super-backlog': 'latest',
+};
+export function readPkgJson(cwd) {
+    const p = join(cwd, 'package.json');
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+export function mergeScripts(pkg, wanted) {
+    const scripts = { ...(pkg.scripts ?? {}) };
+    const added = [];
+    for (const [name, cmd] of Object.entries(wanted)) {
+        if (!(name in scripts)) {
+            scripts[name] = cmd;
+            added.push(name);
+        }
+    }
+    return { pkg: { ...pkg, ...(added.length ? { scripts } : {}) }, added };
+}
+export function addDevDependencies(pkg, deps) {
+    const devDependencies = { ...(pkg.devDependencies ?? {}) };
+    const added = [];
+    for (const [name, spec] of Object.entries(deps)) {
+        if (!(name in devDependencies)) {
+            devDependencies[name] = spec;
+            added.push(name);
+        }
+    }
+    return { pkg: { ...pkg, ...(added.length ? { devDependencies } : {}) }, added };
+}

package/dist/lib/pm.js

@@ -0,0 +1,20 @@
+// src/lib/pm.ts
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function detectPackageManager(cwd) {
+    const has = (f) => existsSync(join(cwd, f));
+    if (!has('package.json'))
+        return null;
+    if (has('pnpm-lock.yaml'))
+        return 'pnpm';
+    if (has('bun.lockb') || has('bun.lock'))
+        return 'bun';
+    return 'npm';
+}
+export function installCmdsFor(pm, pkgs) {
+    switch (pm) {
+        case 'pnpm': return { cmd: 'pnpm', args: ['add', '-D', ...pkgs] };
+        case 'bun': return { cmd: 'bun', args: ['add', '-d', ...pkgs] };
+        default: return { cmd: 'npm', args: ['install', '--save-dev', ...pkgs] };
+    }
+}

package/dist/lib/powershell.js

@@ -0,0 +1,44 @@
+// src/lib/powershell.ts
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+const defaultExecutor = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: 'utf8', windowsHide: true });
+    if (r.error)
+        return { status: null, stdout: '', stderr: String(r.error.message) };
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+export function getEffectiveExecutionPolicy(deps = {}) {
+    const fake = (deps.fakePolicy ?? process.env.SBL_FAKE_POLICY)?.trim();
+    if (fake)
+        return fake;
+    const platform = deps.platform ?? process.platform;
+    if (platform !== 'win32')
+        return null;
+    const executor = deps.executor ?? defaultExecutor;
+    const r = executor('powershell.exe', [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        'Get-ExecutionPolicy',
+    ]);
+    if ((r.status === null || r.status !== 0))
+        return null;
+    const policy = r.stdout.trim();
+    if (policy === '')
+        return null;
+    return policy;
+}
+export function isBlockingExecutionPolicy(policy) {
+    if (!policy)
+        return false;
+    const normalized = policy.trim().toLowerCase();
+    return normalized === 'restricted' || normalized === 'allsigned';
+}
+export function policyWarningLines(policy) {
+    return [
+        `warning: PowerShell execution policy "${policy}" blocks direct npx/npm/sbl calls in PowerShell (.ps1 shims are not loadable)`,
+        '  fix: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned   (one-time, no admin needed)',
+        '  alt: call the .cmd shims explicitly (npx.cmd super-backlog init) or run from cmd.exe',
+        '  note: npm scripts like "npm run board" are unaffected (they execute via cmd.exe)',
+    ];
+}

package/dist/lib/run.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import process from 'node:process';
+export function runCapture(cmd, args, cwd) {
+    // shell on win32 — safe only because callers pass constant args; never pass user input here.
+    const winShell = process.platform === 'win32';
+    const file = winShell && /\s/.test(cmd) ? `"${cmd}"` : cmd;
+    const r = spawnSync(file, args, { cwd, encoding: 'utf8', shell: winShell });
+    if (r.error && (r.status === null || r.status === undefined)) {
+        return { status: 127, stdout: '', stderr: String(r.error.message) };
+    }
+    return {
+        status: r.status ?? 1,
+        stdout: (r.stdout ?? '').toString(),
+        stderr: (r.stderr ?? '').toString(),
+    };
+}
+const EXT = process.platform === 'win32' ? '.cmd' : '';
+export function resolveBacklogBin(cwd) {
+    const local = join(cwd, 'node_modules', '.bin', `backlog${EXT}`);
+    if (existsSync(local))
+        return local;
+    const probe = process.platform === 'win32' ? 'where' : 'which';
+    const w = runCapture(probe, ['backlog'], cwd);
+    if (w.status === 0) {
+        const first = w.stdout.split(/\r?\n/).find(Boolean);
+        if (first)
+            return first.trim().replace(/\.ps1$/i, '.cmd');
+    }
+    return null;
+}

package/dist/lib/validate-task.js

@@ -0,0 +1,22 @@
+export function validateTaskMarkdown(filename, content) {
+    const errors = [];
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+    if (!m)
+        return [`backlog/tasks/${filename}: missing YAML frontmatter (edit tasks via the backlog CLI instead)`];
+    const fm = m[1];
+    const field = (name) => {
+        const fmMatch = new RegExp(`^${name}:\\s*(.*?)\\s*$`, 'm').exec(fm);
+        return fmMatch ? fmMatch[1].replace(/^["']|["']$/g, '') : null;
+    };
+    const stem = filename.replace(/\.md$/, '');
+    const base = stem.includes(' - ') ? stem.split(' - ')[0] : stem;
+    const id = field('id');
+    if (!id)
+        errors.push(`backlog/tasks/${filename}: missing 'id' field`);
+    else if (id.toLowerCase() !== base.toLowerCase())
+        errors.push(`backlog/tasks/${filename}: id '${id}' does not match filename stem '${base}'`);
+    const title = field('title');
+    if (!title)
+        errors.push(`backlog/tasks/${filename}: empty or missing 'title'`);
+    return errors;
+}

package/dist/lib/version.js

@@ -0,0 +1,12 @@
+// src/lib/version.ts
+import { createRequire } from 'node:module';
+import process from 'node:process';
+const require = createRequire(import.meta.url);
+export const KIT_VERSION = require('../../package.json').version ?? '0.0.0';
+export function assertNode20() {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major < 20) {
+        console.error(`super-backlog requires Node >= 20 (found ${process.versions.node}).`);
+        process.exit(1);
+    }
+}

package/dist/lib/yamlmini.js

@@ -0,0 +1,18 @@
+// src/lib/yamlmini.ts
+import { existsSync, readFileSync } from 'node:fs';
+export function readSimpleKeys(filePath, keys) {
+    const out = {};
+    for (const k of keys)
+        out[k] = undefined;
+    if (!existsSync(filePath))
+        return out;
+    const wanted = new Set(keys);
+    for (const line of readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+        if (!m || !wanted.has(m[1]))
+            continue;
+        const raw = m[2].trim();
+        out[m[1]] = raw.replace(/^["'](.*)["']$/, '$1');
+    }
+    return out;
+}

package/dist/templates/claude-pointer.md

@@ -0,0 +1,5 @@
+## Workflow system (managed by super-backlog)
+
+This project uses the combined Backlog.md + Superpowers workflow. Read the
+integration block in AGENTS.md (section between SUPER-BACKLOG markers) and follow
+it. Tasks are managed exclusively through the `backlog` CLI.

package/dist/templates/dashboard-refresh-hook.sh

@@ -0,0 +1,18 @@
+# >>> super-backlog dashboard-refresh {{VERSION}} >>>
+# Regenerates dashboard.html when the just-created commit touched backlog/.
+# Post-commit only: this block NEVER blocks a commit - any failure is just a
+# stderr note and the exit status stays 0.
+root=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -n "$root" ] && [ -f "$root/node_modules/super-backlog/dist/dashboard/regen.js" ]; then
+  touch_backlog=0
+  if ! git rev-parse --verify --quiet HEAD~1 >/dev/null 2>&1; then
+    touch_backlog=1 # initial commit: nothing to diff against - regenerate
+  elif [ -n "$(git diff --name-only HEAD~1 HEAD -- 'backlog/*' 2>/dev/null)" ]; then
+    touch_backlog=1
+  fi
+  if [ "$touch_backlog" -eq 1 ]; then
+    node "$root/node_modules/super-backlog/dist/dashboard/regen.js" >/dev/null 2>&1 || echo "super-backlog: dashboard regeneration failed (see npm run dashboard)" >&2
+  fi
+fi
+exit 0
+# <<< super-backlog dashboard-refresh <<<