outask 0.0.0-stage → 1.7.0

package/scripts/output.mjs

@@ -0,0 +1,67 @@
+import { errorText, fail } from '../src/errors.mjs';
+import { ownValue } from '../src/fields.mjs';
+import { responseBytes } from '../src/limits.mjs';
+import { jsonText, textBuffer } from '../src/response.mjs';
+
+function valueText(value) {
+  if (value === undefined) return '(unset)';
+  return typeof value === 'object' ? jsonText(value, 0) : String(value);
+}
+
+function tableCell(value, maxWidth) {
+  const text = [...valueText(value).replace(/\s+/g, ' ')];
+  return text.length > maxWidth ? `${text.slice(0, maxWidth - 1).join('')}…` : text.join('');
+}
+
+function formatTable(records, fields, maxWidth, buffer) {
+  if ((fields.length - 1) * 2 * (records.length + 1) > responseBytes) return undefined;
+  const rows = [fields, ...records.map((record) => fields.map((field) => ownValue(record, field)))]
+    .map((row) => row.map((value) => tableCell(value, maxWidth)));
+  const widths = fields.map((_, column) => rows.reduce((width, row) => Math.max(width, [...row[column]].length), 0));
+  for (const row of rows) {
+    for (let column = 0; column < fields.length; column++) {
+      if (!buffer.add(row[column])) return undefined;
+      if (column < fields.length - 1 && !buffer.spaces(widths[column] - [...row[column]].length + 2)) return undefined;
+    }
+    if (!buffer.add('\n')) return undefined;
+  }
+  return buffer.finish();
+}
+
+function formatText(records, fields, buffer) {
+  for (let index = 0; index < records.length; index++) {
+    if (index && !buffer.add('\n')) return undefined;
+    for (const field of fields) {
+      if (!buffer.add(field) || !buffer.add(': ') || !buffer.add(valueText(ownValue(records[index], field)))
+        || !buffer.add('\n')) return undefined;
+    }
+  }
+  return buffer.finish();
+}
+
+export function formatOutput(data, fields, { format, maxWidth }, ceiling = responseBytes) {
+  if (format === 'json') {
+    const json = jsonText(data, 2, ceiling - 1);
+    return json === undefined ? undefined : `${json}\n`;
+  }
+  const records = Array.isArray(data) ? data : [data];
+  const buffer = textBuffer(ceiling);
+  if (format === 'ids') {
+    buffer.add(`${records.map((record) => record.id).join(' ')}\n`);
+  } else if (!records.length) buffer.add('no tasks on this page\n');
+  else if (format === 'table') return formatTable(records, fields, maxWidth, buffer);
+  else return formatText(records, fields, buffer);
+  return buffer.finish();
+}
+
+export function printOutput(data, fields, output) {
+  const text = formatOutput(data, fields, output);
+  if (text === undefined) fail('OUTPUT_TOO_LARGE', 'rendered response exceeds 32 KiB; select fewer --fields or a smaller --max-width');
+  process.stdout.write(text);
+}
+
+export function reportError(error) {
+  const code = error.code?.startsWith('ERR_PARSE_ARGS') ? 'INVALID_INPUT' : (error.code ?? 'INVALID_INPUT');
+  process.stderr.write(`${code}: ${errorText(error.message)}\n`);
+  process.exitCode = 1;
+}

package/scripts/schema.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { inspectSchema, materialiseSchema } from '../src/schema.mjs';
+import { fail } from '../src/errors.mjs';
+import { parseProject, parseSchema, projectHelp } from './arguments.mjs';
+import { isMain } from './entry.mjs';
+import { reportError } from './output.mjs';
+
+export const options = {
+  write: { type: 'boolean' }, replace: { type: 'boolean' },
+  'schema-path': { type: 'string' }, help: { type: 'boolean', short: 'h' },
+};
+export const usage = 'Usage: node app/scripts/schema.mjs [project-path] [options]';
+export const help = `${usage}
+
+Inspect the effective task schema as readable JSON, including default stores and groups.
+${projectHelp}Schema inspection needs no task stores. Output is always JSON (a configuration document).
+  --write              Materialise the effective schema at the selected schema path
+  --replace            Allow --write to replace an existing schema; preserves custom fields
+  --schema-path <file>  Select an existing project-relative schema
+  --help, -h           Show this help
+Without a schema, --write creates tasks/task-schema.json. Explicit paths must exist.
+Task records are never changed. Existing stores must validate before writing.
+An empty project can obtain a skeleton; validation needs a task store first.
+Run tasks validate after editing the schema to refresh service metadata.
+`;
+
+export function main(args) {
+  const { values, positionals, tokens } = parseArgs({ args, options, allowPositionals: true, tokens: true });
+  if (values.help) { process.stdout.write(help); return; }
+  const { project } = parseProject(positionals, usage);
+  const schemaPath = parseSchema(values, tokens);
+  if (values.replace && !values.write) fail('INVALID_INPUT', '--replace requires --write');
+  const schema = values.write ? materialiseSchema(project, { schemaPath, replace: values.replace })
+    : inspectSchema(project, { schemaPath });
+  process.stdout.write(`${JSON.stringify(schema, null, 2)}\n`);
+}
+
+if (isMain(import.meta.url)) {
+  try { main(process.argv.slice(2)); } catch (error) { reportError(error); }
+}

package/scripts/search-tasks.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readConfig } from '../src/config.mjs';
+import { fail } from '../src/errors.mjs';
+import { defaultLimit, maxLimit, responseBytes } from '../src/limits.mjs';
+import { textBuffer } from '../src/response.mjs';
+import { defaultSearchFields, searchTasks } from '../src/search.mjs';
+import { cacheOptions, commonHelp, commonOptions, parseInteger, parseOutput, parseProject, parseSchema, parseSelection, projectHelp } from './arguments.mjs';
+import { nextCommand } from './continuation.mjs';
+import { isMain } from './entry.mjs';
+import { formatOutput, reportError } from './output.mjs';
+
+export const options = {
+  ...commonOptions,
+  format: { type: 'string' },
+  'search-fields': { type: 'string' }, cursor: { type: 'string' },
+  limit: { type: 'string', default: String(defaultLimit) },
+};
+export const usage = 'Usage: node app/scripts/search-tasks.mjs [project-path] <query> [options]';
+export const help = `${usage}
+
+${projectHelp}Reads never change task files.
+  --search-fields <names>  Comma-separated fields searched with OR semantics
+                           (default: ${defaultSearchFields.join(',')})
+  --fields <names>     Comma-separated result fields (default: id,title,status)
+${commonHelp.replace('  --fields <names>     Comma-separated field names\n', '').replace('text (default), table, json or ids', 'table (default), text, json or ids')}  --limit <n>         Page size from 1 to 50 (default: 10); responses up to 32 KiB
+  --cursor <cursor>    Continue the same search from an opaque cursor
+`;
+
+function splitNames(value, option) {
+  const names = value.split(',').map((name) => name.trim());
+  if (names.some((name) => !name)) fail('INVALID_INPUT', `${option} field names cannot be empty`);
+  return names;
+}
+
+function pageInfo(page, args, tokens, invocation) {
+  const buffer = textBuffer();
+  buffer.add(`Showing ${page.tasks.length} search match${page.tasks.length === 1 ? '' : 'es'}.\n`);
+  for (const advisory of page.advisories ?? []) {
+    buffer.add(`Advisory ${advisory.code}: ${advisory.message} (${advisory.elapsed_ms} ms)\n`);
+  }
+  if (page.hasMore) {
+    const command = nextCommand(args, tokens, 'cursor', page.next_cursor, invocation);
+    if (command === undefined) return undefined;
+    buffer.add(`Next page: ${command}\n`);
+  }
+  return buffer.finish();
+}
+
+function showPage(page, output, args, tokens, invocation) {
+  if (output.format === 'json') {
+    const text = formatOutput(page, page.fields, output);
+    if (text === undefined) fail('OUTPUT_TOO_LARGE', 'rendered search response exceeds 32 KiB; select fewer --fields or --search-fields');
+    process.stdout.write(text);
+    return;
+  }
+  const info = pageInfo(page, args, tokens, invocation);
+  if (info === undefined) fail('OUTPUT_TOO_LARGE', 'search guidance exceeds 32 KiB; shorten the query or field selections');
+  const displayFields = [...page.fields, 'matched_fields', 'snippets'];
+  const text = formatOutput(page.tasks, displayFields, output, responseBytes - Buffer.byteLength(info, 'utf8'));
+  if (text === undefined) fail('OUTPUT_TOO_LARGE', 'rendered search response exceeds 32 KiB; select fewer --fields or --search-fields');
+  process.stdout.write(text);
+  process.stderr.write(info);
+}
+
+export function main(args, guidance) {
+  const { values, positionals, tokens } = parseArgs({ args, options, allowPositionals: true, tokens: true });
+  if (values.help) {
+    process.stdout.write(help);
+    return;
+  }
+  const { project, id: query } = parseProject(positionals, usage, true);
+  values.format ??= 'table';
+  const output = parseOutput(values);
+  const selection = parseSelection(values);
+  const queryOptions = {
+    ...selection,
+    searchFields: values['search-fields'] === undefined
+      ? defaultSearchFields : splitNames(values['search-fields'], '--search-fields'),
+    limit: parseInteger(values.limit, '--limit', 1, maxLimit), cursor: values.cursor,
+    schemaPath: parseSchema(values, tokens),
+    slowQueryMs: readConfig(guidance?.config).slowQueryMs,
+    refreshMode: 'detached',
+    ...cacheOptions(values),
+  };
+  const page = searchTasks(project, query, queryOptions);
+  showPage(page, output, guidance?.args ?? args, guidance?.tokens ?? tokens, guidance?.invocation);
+}
+
+if (isMain(import.meta.url)) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    reportError(error);
+  }
+}

package/scripts/task-write-input.mjs

@@ -0,0 +1,80 @@
+import { fail } from '../src/errors.mjs';
+import { decodeText, parseJson, readBudget, readJson } from '../src/input.mjs';
+import { inputBytes } from '../src/limits.mjs';
+import { parseInteger } from './arguments.mjs';
+
+export const taskWriteOptions = {
+  json: { type: 'string', multiple: true }, input: { type: 'string', multiple: true },
+  title: { type: 'string' }, status: { type: 'string' }, priority: { type: 'string' }, blockers: { type: 'string' },
+  store: { type: 'string' }, format: { type: 'string', default: 'json' }, help: { type: 'boolean', short: 'h' },
+  'schema-path': { type: 'string' },
+};
+export const taskWriteHelp = `  --title <text>      Replace the title
+  --status <status>   Set an exact configured status
+  --priority <text>   Replace priority
+  --blockers <ids>    Replace blockers with comma-separated positive IDs; '' clears
+  --json <object>     JSON input string, exclusive with --input; neither is repeatable
+  --input <file|->    Read JSON from a file or stdin (-); no interactive prompts
+  --store <name>      Destination store (one); resolve ambiguous destinations
+  --schema-path <file> Project-relative schema file; overrides automatic selection
+  --format json      Complete resulting task as JSON (default and only format)
+  --help, -h          Show this help
+Flags may mix with JSON only for disjoint fields. A field mentioned in any patch
+operation cannot also be supplied by a flag. Repeated scalar options are errors.
+`;
+
+export function checkOptions(tokens) {
+  const seen = new Set();
+  for (const token of tokens) {
+    if (token.kind !== 'option') continue;
+    if (seen.has(token.name)) fail('INVALID_INPUT', `--${token.name} may be supplied only once`);
+    seen.add(token.name);
+  }
+}
+
+export async function readTaskWriteInput(values, updating) {
+  const count = (values.json?.length ?? 0) + (values.input?.length ?? 0);
+  if (count > 1) fail('INVALID_INPUT', 'supply exactly one --json or --input source; repeated or combined sources are not allowed');
+  let input;
+  if (values.json !== undefined) {
+    const json = values.json[0];
+    if (Buffer.byteLength(json, 'utf8') > inputBytes) fail('INPUT_TOO_LARGE', 'task input exceeds the 8 MiB read budget');
+    input = parseJson(json, '--json');
+  } else if (values.input !== undefined) {
+    const source = values.input[0];
+    if (source === '-') {
+      const chunks = [];
+      let length = 0;
+      for await (const chunk of process.stdin) {
+        length += chunk.length;
+        if (length > inputBytes) fail('INPUT_TOO_LARGE', 'task input exceeds the 8 MiB read budget');
+        chunks.push(chunk);
+      }
+      input = parseJson(decodeText(Buffer.concat(chunks, length), 'stdin'), 'stdin');
+    } else {
+      if (!source) fail('INVALID_INPUT', '--input requires a file path or -');
+      input = readJson(source, readBudget());
+    }
+  } else input = {};
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail('INVALID_INPUT', 'JSON input must be an object');
+  const fields = {};
+  for (const name of ['title', 'status', 'priority', 'blockers']) {
+    if (values[name] === undefined) continue;
+    const collision = updating
+      ? ['set', 'add', 'remove'].some((operation) => input[operation] && Object.hasOwn(input[operation], name))
+        || (Array.isArray(input.unset) && input.unset.includes(name))
+      : Object.hasOwn(input, name);
+    if (collision) fail('INVALID_INPUT', `--${name} conflicts with JSON field ${name}`);
+    fields[name] = name === 'blockers'
+      ? (values[name] === '' ? [] : values[name].split(',').map((id) => parseInteger(id.trim(), '--blockers', 1)))
+      : values[name];
+  }
+  if (!count && !Object.keys(fields).length) fail('INVALID_INPUT', 'supply standard field flags, --json or --input');
+  if (!Object.keys(fields).length) return input;
+  if (!updating) return { ...input, ...fields };
+  // Do not repair a malformed patch while adding convenient flags.
+  if (input.set !== undefined && (!input.set || typeof input.set !== 'object' || Array.isArray(input.set))) {
+    fail('INVALID_INPUT', 'set must be an object');
+  }
+  return { ...input, set: { ...input.set, ...fields } };
+}

package/scripts/transition-task.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runLifecycle } from './lifecycle.mjs';
+runLifecycle(false);

package/scripts/update-release.mjs

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { spawnSync } from 'node:child_process';
+
+const repository = 'henryh/outask';
+export const latestReleaseUrl = `https://api.github.com/repos/${repository}/releases/latest`;
+
+export function updateTarget(platform = process.platform, arch = process.arch) {
+  const target = `${platform === 'darwin' ? 'macos' : platform === 'win32' ? 'windows' : platform}-${arch}`;
+  if (!['linux-x64', 'macos-arm64', 'windows-x64'].includes(target)) throw new Error(`Unsupported platform ${target}; use a supported native host`);
+  return target;
+}
+
+export function latestAsset(release, target) {
+  if (release.draft !== false || release.prerelease !== false || !/^v\d+\.\d+(?:\.\d+)?$/.test(release.tag_name)) {
+    throw new Error('GitHub Latest did not return a stable published release');
+  }
+  const version = release.tag_name.slice(1);
+  const name = `Outask-${version}-${target}.tar.gz`;
+  const url = `https://github.com/${repository}/releases/download/${release.tag_name}/${name}`;
+  const asset = release.assets?.find((item) => item.name === name && item.state === 'uploaded');
+  if (!asset || asset.browser_download_url !== url) throw new Error(`Latest release has no supported archive ${name}`);
+  return { ...asset, version };
+}
+
+function run(args) {
+  const result = spawnSync(args[0], args.slice(1), { encoding: 'utf8', timeout: 120000, maxBuffer: 8 * 1024 * 1024 });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error((result.stderr || result.stdout || `${args[0]} exited ${result.status}`).trim());
+  return result.stdout;
+}
+
+export async function updateRelease({ destination, bin, releases, fetchRelease = fetch, target = updateTarget(), log = console.log }) {
+  let work;
+  let stage = 'resolve latest release';
+  try {
+    const request = async (url) => {
+      const response = await fetchRelease(url, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'outask-installer' }, signal: AbortSignal.timeout(120000) });
+      if (!response.ok) throw new Error(`HTTP ${response.status} from ${url}`);
+      return response;
+    };
+    const asset = latestAsset(await (await request(latestReleaseUrl)).json(), target);
+    const installed = JSON.parse(readFileSync(join(destination, 'release.json'), 'utf8'));
+    if (installed.version === asset.version && installed.target === target) {
+      log(`Outask v${asset.version} is already current.`);
+      return;
+    }
+    work = mkdtempSync(join(tmpdir(), 'outask-update-'));
+    const archive = join(work, asset.name);
+    stage = `download ${asset.name}`;
+    const response = await request(asset.browser_download_url);
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(archive));
+    const bytes = readFileSync(archive);
+    if (bytes.length !== asset.size) throw new Error('Archive size differs from GitHub; retry the download');
+    if (asset.digest?.startsWith('sha256:') && `sha256:${createHash('sha256').update(bytes).digest('hex')}` !== asset.digest) {
+      throw new Error('Archive SHA256 differs from GitHub; retry the download');
+    }
+    stage = 'extract latest archive';
+    const names = run(['tar', '-tzf', archive]).trim().split(/\r?\n/);
+    const directory = 'Outask';
+    if (names.some((name) => !(name === directory || name.startsWith(`${directory}/`)) || name.includes('\\') || name.split('/').includes('..'))) {
+      throw new Error(`Archive contains paths outside ${directory}`);
+    }
+    run(['tar', '-xzf', archive, '-C', work]);
+    const source = join(work, directory);
+    const metadata = JSON.parse(readFileSync(join(source, 'release.json'), 'utf8'));
+    if (metadata.version !== asset.version || metadata.target !== target) throw new Error('Archive metadata differs from GitHub Latest');
+    stage = 'install latest release';
+    // The installer stages and verifies its payload before replacing the working copy.
+    const output = run([process.execPath, join(source, 'app/scripts/install-release.mjs'), 'install', '--bin-dir', bin, '--release-root', releases]);
+    log(output.trim());
+    log(`Updated to Outask v${asset.version}.`);
+  } catch (error) {
+    throw new Error(`UPDATE_FAILED: could not ${stage}: ${error.message}. Check network access, tar and directory permissions, then retry update.`);
+  } finally {
+    if (work) rmSync(work, { recursive: true, force: true });
+  }
+}

package/scripts/update-task.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { updateTask } from '../src/update.mjs';
+import { fail } from '../src/errors.mjs';
+import { parseInteger, parseProject, parseSchema, projectHelp } from './arguments.mjs';
+import { isMain } from './entry.mjs';
+import { checkOptions, taskWriteHelp, readTaskWriteInput, taskWriteOptions } from './task-write-input.mjs';
+import { reportError } from './output.mjs';
+
+export const options = { ...taskWriteOptions, 'if-updated-at': { type: 'string' } };
+export const usage = 'Usage: node app/scripts/update-task.mjs [project-path] <id> [field options | --json <object> | --input <file|->] [options]';
+export const help = `${usage}\n${projectHelp}Update one retained task. Patch: {set:{field:value},add:{field:[values]},remove:{field:[values]},unset:[fields]}. Each field may occur once. Text, objects and arrays replace completely.\nArray additions deduplicate structurally; removals delete all equal elements. Absent removals and duplicate-only additions are silent no-ops. unset removes optional fields.\nid and updated_at cannot be patched. Actual changes advance updated_at; no-ops preserve it. --if-updated-at checks the exact timestamp, including no-ops.\n${taskWriteHelp}  --if-updated-at <timestamp>  Reject stale edits using the last-read UTC millisecond timestamp\n`;
+
+export async function main(args) {
+  const { values, positionals, tokens } = parseArgs({ args, allowPositionals: true, tokens: true, options });
+  if (values.help) { process.stdout.write(help); return; }
+  checkOptions(tokens);
+  const { project, id } = parseProject(positionals, usage, true);
+  if (values.format !== 'json') fail('INVALID_INPUT', 'format must be json');
+  const input = await readTaskWriteInput(values, true);
+  const task = updateTask(project, parseInteger(id, 'id', 1), input, {
+    store: values.store, ifUpdatedAt: values['if-updated-at'], schemaPath: parseSchema(values, tokens),
+  });
+  process.stdout.write(`${JSON.stringify(task, null, 2)}\n`);
+}
+
+if (isMain(import.meta.url)) {
+  try { await main(process.argv.slice(2)); } catch (error) { reportError(error); }
+}

package/scripts/validate-task-stores.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { fail } from '../src/errors.mjs';
+import { validateProject } from '../src/validation.mjs';
+import { parseProject, parseSchema, projectHelp } from './arguments.mjs';
+import { isMain } from './entry.mjs';
+import { reportError } from './output.mjs';
+
+export const options = {
+  format: { type: 'string', default: 'text' }, 'schema-path': { type: 'string' }, help: { type: 'boolean', short: 'h' },
+};
+export const usage = 'Usage: node app/scripts/validate-task-stores.mjs [project-path] [--format text|json]';
+export const help = `${usage}\n${projectHelp}Validate all retained stores and refresh tasks/.task-tracker.json after success.\nTask files remain unchanged. --schema-path selects a project-relative schema file.\n`;
+
+export function main(args) {
+  const { values, positionals, tokens } = parseArgs({ args, allowPositionals: true, options, tokens: true });
+  if (values.help) {
+    process.stdout.write(help);
+    return;
+  }
+  const { project } = parseProject(positionals, usage);
+  if (!['text', 'json'].includes(values.format)) fail('INVALID_INPUT', usage);
+  const result = validateProject(project, { schemaPath: parseSchema(values, tokens) });
+  process.stdout.write(values.format === 'json' ? `${JSON.stringify(result)}\n`
+    : `Validation passed (${result.tasks} tasks, ${result.stores} stores). Counter: ${result.counter}; service state ${result.refreshed ? 'refreshed' : 'unchanged'}.\n`);
+}
+
+if (isMain(import.meta.url)) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    reportError(error);
+  }
+}

package/src/blockers.mjs

@@ -0,0 +1,134 @@
+import { fail } from './errors.mjs';
+import { advise, cacheSupported, cacheUnavailable, checkCacheOptions, onceAdvisory } from './cache.mjs';
+import { defaultLimit, maxLimit, responseBytes } from './limits.mjs';
+import { jsonBytes } from './response.mjs';
+import { indexedBlockers, scheduleSearchRefresh, searchSourceState } from './search-index.mjs';
+import { projectBudget } from './input.mjs';
+import { openProject, recordEntries } from './stores.mjs';
+
+export const defaultDepth = 1;
+export const maxDepth = 20;
+
+function findCycle(id, edges) {
+  const links = new Map();
+  for (const { from, to } of edges) {
+    if (!links.has(from)) links.set(from, []);
+    links.get(from).push(to);
+  }
+  const visited = new Set();
+  const path = [];
+  // The edge limit bounds this recursion, including the returned cycle path.
+  function visit(current) {
+    const ancestor = path.indexOf(current);
+    if (ancestor !== -1) return [...path.slice(ancestor), current];
+    if (visited.has(current)) return [];
+    visited.add(current);
+    path.push(current);
+    for (const next of links.get(current) ?? []) {
+      const cycle = visit(next);
+      if (cycle.length) return cycle;
+    }
+    path.pop();
+    return [];
+  }
+  return visit(id);
+}
+
+function inspectGraph(id, activeLinks, depth, limit) {
+  const graph = {
+    depth, limit, edges: [], cycle: [], cycleStatus: 'none',
+    truncated: { depth: false, limit: false, response: false },
+  };
+  const visited = new Set([id]);
+  const pending = [{ id, depth: 0 }];
+  for (let index = 0; index < pending.length; index++) {
+    const current = pending[index];
+    const blockers = activeLinks(current.id);
+    if (current.depth === depth) {
+      if (blockers.length) graph.truncated.depth = true;
+      continue;
+    }
+    for (const to of blockers) {
+      if (graph.edges.length === limit) {
+        graph.truncated.limit = true;
+        return graph;
+      }
+      graph.edges.push({ from: current.id, to });
+      if (!visited.has(to)) {
+        visited.add(to);
+        pending.push({ id: to, depth: current.depth + 1 });
+      }
+    }
+  }
+  return graph;
+}
+
+export function inspectBlockers(projectPath, id, options = {}) {
+  if (!Number.isSafeInteger(id) || id <= 0) fail('INVALID_INPUT', 'id must be a positive safe integer');
+  if (options === null || typeof options !== 'object' || Array.isArray(options)
+    || Object.keys(options).some((key) => !['depth', 'limit', 'schemaPath', 'refreshMode', 'noCache', 'onAdvisory'].includes(key))) {
+    fail('INVALID_INPUT', 'options contains an unsupported blocker inspection setting');
+  }
+  const { noCache = false, onAdvisory } = options;
+  checkCacheOptions(noCache, onAdvisory);
+  const notify = onceAdvisory(onAdvisory);
+  const { depth = defaultDepth, limit = defaultLimit } = options;
+  if (!Number.isSafeInteger(depth) || depth < 1 || depth > maxDepth) {
+    fail('INVALID_INPUT', `depth must be an integer from 1 to ${maxDepth}`);
+  }
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxLimit) {
+    fail('INVALID_INPUT', `limit must be an integer from 1 to ${maxLimit}`);
+  }
+  const budget = projectBudget();
+  budget.fingerprints = {};
+  const project = openProject(projectPath, budget, false, true, options.schemaPath);
+  const useCache = !noCache && cacheSupported(notify);
+  const state = useCache ? searchSourceState(project) : undefined;
+  let active = useCache ? indexedBlockers(project, state) : undefined;
+  if (!active) {
+    if (useCache) {
+      try {
+        scheduleSearchRefresh(project.root, {
+          schemaPath: options.schemaPath, detached: options.refreshMode === 'detached',
+        });
+      } catch { advise(notify, cacheUnavailable); }
+    }
+    const { entries } = recordEntries(project, { group: 'Active' });
+    active = new Map();
+    for (const { record } of entries) {
+      active.set(record.id, Object.hasOwn(record, 'blockers') ? { blockers: record.blockers } : {});
+    }
+  }
+  try {
+    if (!active.has(id)) fail('TASK_NOT_FOUND', `task ${id} was not found in Active; inspect history separately with get-task.mjs`);
+    const links = new Map();
+    function activeLinks(current) {
+      if (links.has(current)) return links.get(current);
+      const blockers = active.get(current).blockers;
+      if (blockers !== undefined && (!Array.isArray(blockers)
+        || !blockers.every((blocker) => Number.isSafeInteger(blocker) && blocker > 0))) {
+        fail('INVALID_STORE', `task ${current}: blockers must be an array of positive safe integer local IDs, or omitted`);
+      }
+      const selected = [...new Set((blockers ?? []).filter((blocker) => active.has(blocker)))].sort((a, b) => a - b);
+      links.set(current, selected);
+      return selected;
+    }
+    const activeBlockers = activeLinks(id);
+    const graph = inspectGraph(id, activeLinks, depth, limit);
+    const result = { id, eligible: activeBlockers.length === 0, activeBlockers, graph };
+    // Preserve exact direct eligibility; only graph details may be shortened.
+    while (true) {
+      graph.cycle = findCycle(id, graph.edges);
+      graph.cycleStatus = graph.cycle.length ? 'found'
+        : Object.values(graph.truncated).some(Boolean) ? 'unknown' : 'none';
+      if (jsonBytes(result) + 1 <= responseBytes) return result;
+      if (!graph.edges.length) {
+        fail('OUTPUT_TOO_LARGE', `task ${id}: exact active blocker result exceeds 32 KiB; inspect smaller Active task selections with list/get`);
+      }
+      graph.edges.pop();
+      graph.truncated.response = true;
+    }
+  } finally {
+    active.close?.();
+  }
+}

package/src/cache.mjs

@@ -0,0 +1,50 @@
+import { databaseSync } from './sqlite.mjs';
+
+export const cacheUnavailable = Object.freeze({
+  code: 'CACHE_UNAVAILABLE',
+  message: 'SQLite cache acceleration is unavailable; authoritative JSON was used.',
+});
+export const cacheFallback = Object.freeze({
+  code: 'CACHE_FALLBACK',
+  message: 'A current SQLite cache was unavailable; authoritative JSON was used while a refresh was requested.',
+});
+
+let support;
+
+export function checkCacheOptions(noCache, onAdvisory) {
+  if (typeof noCache !== 'boolean') throw Object.assign(new Error('noCache must be a boolean'), { code: 'INVALID_INPUT' });
+  if (onAdvisory !== undefined && typeof onAdvisory !== 'function') {
+    throw Object.assign(new Error('onAdvisory must be a function'), { code: 'INVALID_INPUT' });
+  }
+}
+
+export function advise(onAdvisory, advisory) {
+  onAdvisory?.(advisory);
+}
+
+export function onceAdvisory(onAdvisory) {
+  let sent = false;
+  return (advisory) => {
+    if (sent) return;
+    sent = true;
+    advise(onAdvisory, advisory);
+  };
+}
+
+export function cacheSupported(onAdvisory) {
+  if (support === undefined) {
+    let database;
+    try {
+      const DatabaseSync = databaseSync();
+      database = new DatabaseSync(':memory:');
+      database.exec('SELECT 1');
+      support = true;
+    } catch {
+      support = false;
+    } finally {
+      try { database?.close(); } catch { support = false; }
+    }
+  }
+  if (!support) advise(onAdvisory, cacheUnavailable);
+  return support;
+}

package/src/config.mjs

@@ -0,0 +1,30 @@
+import { homedir } from 'node:os';
+import { existsSync } from 'node:fs';
+import { configPath } from './locations.mjs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fail } from './errors.mjs';
+import { readBudget, readJson } from './input.mjs';
+
+export const defaultSlowQueryMs = 150;
+
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const absolute = (value) => typeof value === 'string' && isAbsolute(value) && !value.includes('\0');
+
+export function readConfig(config, env = process.env) {
+  const current = configPath(env);
+  const legacy = join(env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config'), 'task-tracker', 'config.json');
+  const path = resolve(config ?? env.TASK_TRACKER_CONFIG ?? (existsSync(current) || !existsSync(legacy) ? current : legacy));
+  const settings = readJson(path, readBudget(), true) ?? {};
+  if (!object(settings)) fail('INVALID_CONFIG', `${path}: program configuration must be an object`);
+  if ((settings.projects_root !== undefined && !absolute(settings.projects_root))
+    || (settings.projects !== undefined && (!object(settings.projects)
+      || Object.entries(settings.projects).some(([key, value]) => !key || key === '.' || key === '..'
+        || /[\\/\0]/.test(key) || !absolute(value))))) {
+    fail('INVALID_CONFIG', `${path}: projects_root and projects mappings must use absolute directory paths and simple names`);
+  }
+  if (settings.slow_query_ms !== undefined
+    && (!Number.isSafeInteger(settings.slow_query_ms) || settings.slow_query_ms < 0)) {
+    fail('INVALID_CONFIG', `${path}: slow_query_ms must be a non-negative safe integer`);
+  }
+  return { path, settings, slowQueryMs: settings.slow_query_ms ?? defaultSlowQueryMs };
+}