outask 0.0.0-stage → 1.7.0

package/scripts/install-migration.mjs

@@ -0,0 +1,82 @@
+import { cpSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, symlinkSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { configPath } from '../src/locations.mjs';
+
+export function legacyLocations(env = process.env) {
+  const home = process.platform === 'win32' ? env.USERPROFILE || homedir() : env.HOME || homedir();
+  return [join(home, '.local/share/task-tracker'), join(home, '.local/share/task-tracker/releases'),
+    join(home, 'Library/Application Support'), join(env.LOCALAPPDATA || join(home, 'AppData/Local'), 'Programs')];
+}
+
+export function legacyConfig(env = process.env) {
+  const home = env.HOME || homedir();
+  const path = join(env.XDG_CONFIG_HOME || join(home, '.config'), 'task-tracker/config.json');
+  // An explicitly selected registry is never moved by an application install.
+  if (env.TASK_TRACKER_CONFIG || !existsSync(path)) return undefined;
+  const target = resolve(configPath(env));
+  if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+    throw new Error(`CONFIG_MIGRATION_REQUIRED: ${target} is a user-managed symlink; select your registry explicitly with TASK_TRACKER_CONFIG`);
+  }
+  if (lstatSync(path).isSymbolicLink() && resolve(dirname(path), readlinkSync(path)) === resolve(target)) {
+    return { source: path, target };
+  }
+  // A directory alias may already expose exactly the canonical file. Do not
+  // replace that file with a link to itself or relocate user-managed folders.
+  if (existsSync(target) && realpathSync(path) === realpathSync(target)) return undefined;
+  if (!lstatSync(path).isFile() || [dirname(path), dirname(dirname(path))].some(directory => lstatSync(directory).isSymbolicLink())) {
+    throw new Error(`CONFIG_MIGRATION_REQUIRED: ${path} uses a symlink or non-file; select it explicitly with TASK_TRACKER_CONFIG to preserve that external registry`);
+  }
+  return { source: path, target };
+}
+
+// Delete only a confirmed managed payload. Unrecognised files stay in place;
+// their presence must never turn an old application directory into trash.
+export function retirePayload(path, payload) {
+  for (const name of payload) rmSync(join(path, name), { recursive: true, force: true });
+  if (readdirSync(path).length === 0) rmdirSync(path);
+}
+
+export function obsoleteInstalls(roots, destination, managed) {
+  const result = [];
+  for (const root of new Set(roots)) {
+    if (!existsSync(root) || !lstatSync(root).isDirectory()) continue;
+    for (const name of readdirSync(root)) {
+      const path = join(root, name);
+      if (path !== destination && !lstatSync(path).isSymbolicLink() && managed(path)) result.push(path);
+    }
+  }
+  return result;
+}
+
+export function retireConfig(migration) {
+  if (!migration) return;
+  if (!existsSync(migration.target)) {
+    mkdirSync(dirname(migration.target), { recursive: true });
+    const staged = `${migration.target}.outask-${randomUUID()}`;
+    try {
+      cpSync(migration.source, staged, { errorOnExist: true, force: false });
+      // Publish complete bytes without overwriting a registry created meanwhile.
+      try { linkSync(staged, migration.target); } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+      }
+    } finally { rmSync(staged, { force: true }); }
+  }
+  if (!readFileSync(migration.source).equals(readFileSync(migration.target))) {
+    throw new Error('CONFIG_CONFLICT: registry changed during installation; both files were retained for reconciliation');
+  }
+  const temporary = `${migration.source}.outask-${randomUUID()}`;
+  let created = false;
+  try {
+    if (process.platform === 'win32') linkSync(migration.target, temporary);
+    else symlinkSync(migration.target, temporary);
+    created = true;
+    renameSync(temporary, migration.source);
+    created = false;
+  } catch (error) {
+    throw new Error(`CONFIG_MIGRATION_REQUIRED: could not link the legacy registry (${error.code}); neither settings copy was deleted. Select an external registry with TASK_TRACKER_CONFIG if its filesystem cannot provide the link`);
+  } finally {
+    if (created) rmSync(temporary, { force: true });
+  }
+}

package/scripts/install-path.mjs

@@ -0,0 +1,105 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+const managedBlocks = /^# Outask command path\ncase ":\$\{PATH-\}:" in\n  \*:(.+):\*\) ;;\n  \*\) export PATH=\1:"\$PATH" ;;\nesac\n/gm;
+
+// Both installers configure future terminals after the command is installed.
+// Profile errors must not turn a usable installation into a reported failure.
+export function configurePath(bin, { env = process.env, platform = process.platform } = {}) {
+  if (platform === 'win32') return configureWindowsPath(bin, env);
+  const home = env.HOME || homedir();
+  const shell = basename(env.SHELL || '');
+  const setting = `export PATH=${quote(bin)}:"$PATH"`;
+  const messages = [`Run immediately: ${quote(join(bin, 'outask'))} --help`];
+  let profiles;
+  if (shell === 'zsh') {
+    const directory = env.ZDOTDIR === undefined ? home : resolve(env.ZDOTDIR);
+    profiles = [join(directory, '.zprofile')];
+    if (platform === 'linux') profiles.push(join(directory, '.zshrc'));
+  } else if (shell === 'bash') {
+    const login = ['.bash_profile', '.bash_login', '.profile'].map((name) => join(home, name));
+    profiles = [join(home, '.bashrc'), login.find(existsSync) || join(home, platform === 'darwin' ? '.bash_profile' : '.profile')];
+  } else {
+    messages.push(`Automatic PATH setup is unavailable for ${shell || 'an unknown shell'}. Add ${setting} to your shell startup file, then open a new terminal.`);
+    return messages;
+  }
+  // Literal quoting also protects shell pattern characters in custom paths.
+  const block = `# Outask command path\ncase ":\${PATH-}:" in\n  *:${quote(bin)}:*) ;;\n  *) ${setting} ;;\nesac\n`;
+  // A shell change must not leave the application's old generated paths in
+  // another shell's existing startup files. Only complete managed blocks count.
+  const candidates = ['.bashrc', '.bash_profile', '.bash_login', '.profile', '.zprofile', '.zshrc'].map(name => join(home, name));
+  if (env.ZDOTDIR !== undefined) candidates.push(join(resolve(env.ZDOTDIR), '.zprofile'), join(resolve(env.ZDOTDIR), '.zshrc'));
+  for (const profile of candidates) {
+    try {
+      if (existsSync(profile)) {
+        const contents = readFileSync(profile, 'utf8');
+        if (contents.replace(managedBlocks, '') !== contents) profiles.push(profile);
+      }
+    } catch (error) { messages.push(`Cannot inspect legacy PATH blocks in ${profile}: ${error.message}`); }
+  }
+  for (const profile of new Set(profiles)) {
+    try {
+      const original = existsSync(profile) ? readFileSync(profile, 'utf8') : '';
+      // Match the complete generated block, including the identical quoted
+      // path in the test and assignment. Other user shell code is untouched.
+      const contents = original.replace(managedBlocks, '');
+      const updated = `${contents && !contents.endsWith('\n') ? `${contents}\n` : contents}${block}`;
+      if (original !== updated) {
+        mkdirSync(dirname(profile), { recursive: true });
+        writeFileSync(profile, updated, { mode: 0o600 });
+      }
+      messages.push(`PATH configured in ${profile}.`);
+    } catch (error) {
+      messages.push(`Command installed at ${join(bin, 'outask')}; PATH setup failed for ${profile}: ${error.message}. Add ${setting} to that startup file manually.`);
+    }
+  }
+  messages.push('Open a new terminal after PATH setup to use outask by name. The current terminal PATH is unchanged.');
+  return messages;
+}
+
+function configureWindowsPath(bin, env) {
+  const launcher = join(bin, 'outask.cmd');
+  const messages = [`Run immediately in PowerShell: & "${launcher}" --help`, `Run immediately in cmd.exe: "${launcher}" --help`];
+  // Read the raw registry value so expandable entries and its value kind survive.
+  const script = `
+$ErrorActionPreference = 'Stop'
+$key = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey('Environment')
+try {
+  $raw = [string]$key.GetValue('Path', '', [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
+  $kind = [Microsoft.Win32.RegistryValueKind]::ExpandString
+  if ($key.GetValueNames() -contains 'Path') { $kind = $key.GetValueKind('Path') }
+  $bin = $env:OUTASK_INSTALL_BIN
+  $normal = $bin.TrimEnd('\\').ToLowerInvariant()
+  $kept = @($raw.Split(';') | Where-Object {
+    $entry = [Environment]::ExpandEnvironmentVariables($_.Trim().Trim('"')).TrimEnd('\\').ToLowerInvariant()
+    $entry -ne $normal
+  }) -join ';'
+  $separator = if ($kept.Length -eq 0 -or $kept.EndsWith(';')) { '' } else { ';' }
+  $updated = $kept + $separator + $bin
+  if ($updated -ne $raw) { $key.SetValue('Path', $updated, $kind) }
+} finally { $key.Dispose() }
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class OutaskEnvironment {
+  [DllImport("user32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, UIntPtr parameter, string value, uint flags, uint timeout, out UIntPtr result);
+}
+'@
+$result = [UIntPtr]::Zero
+if ([OutaskEnvironment]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$result) -eq [IntPtr]::Zero) {
+  throw 'User PATH was saved, but Windows environment-change notification failed; restart your terminal host or sign out and back in.'
+}
+`;
+  const result = spawnSync('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script], {
+    env: { ...env, OUTASK_INSTALL_BIN: bin }, encoding: 'utf8', windowsHide: true, timeout: 30000,
+  });
+  if (result.error || result.status !== 0) {
+    messages.push(`Command installed at ${launcher}; user PATH setup failed: ${result.error?.message || result.stderr?.trim() || result.status}. Add ${bin} to your user PATH manually.`);
+  } else messages.push(`PATH configured in the current user's Windows environment: ${bin}.`);
+  messages.push('Open a new PowerShell or cmd.exe terminal to use outask by name. An already-open terminal keeps its existing PATH; launch from the printed path immediately.');
+  return messages;
+}

package/scripts/install-release.mjs

@@ -0,0 +1,252 @@
+import { accessSync, constants, cpSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { commandNames, packageNames, installLocations, windowsLauncher, launcherEntry } from './install-launcher.mjs';
+import { configurePath } from './install-path.mjs';
+import { updateRelease } from './update-release.mjs';
+import { legacyLocations, legacyConfig, obsoleteInstalls, retireConfig, retirePayload } from './install-migration.mjs';
+
+const windows = process.platform === 'win32';
+// Node 22's native recursive copy can misplace UTF-8 Windows paths. A filter
+// selects its JavaScript traversal without excluding any files or changing links.
+const copyOptions = { recursive: true, verbatimSymlinks: true, ...(windows ? { filter: () => true } : {}) };
+const defaults = installLocations();
+const root = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+const publicInstallers = { 'linux-x64': 'install.sh', 'macos-arm64': 'Install.command', 'windows-x64': 'Install.cmd' };
+const managedPayload = ['app', 'bin', 'install.sh', 'install.mjs', 'install-path.mjs', 'install-launcher.mjs',
+  ...(!windows ? ['install.cmd'] : []), 'Install.command', 'Install.cmd', 'release.json', 'README.md'];
+function inspect(path) {
+  try { return lstatSync(path); } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+function canonical(path) {
+  try { return realpathSync(path); } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const parent = dirname(path);
+    return parent === path ? path : join(canonical(parent), basename(path));
+  }
+}
+function executable(path) {
+  try { accessSync(path, constants.X_OK); return !lstatSync(path).isDirectory(); } catch { return false; }
+}
+function startupFile(path) {
+  const result = { path };
+  try {
+    const stat = lstatSync(path);
+    result.type = stat.isFile() ? 'file' : stat.isDirectory() ? 'directory' : 'other';
+    result.size = stat.size;
+  } catch (error) { result.statError = error.code; }
+  try { result.realpath = realpathSync(path); } catch (error) { result.realpathError = error.code; }
+  try { result.readBytes = readFileSync(path).length; } catch (error) { result.readError = error.code; }
+  return result;
+}
+function managed(path) {
+  try {
+    const metadata = JSON.parse(readFileSync(join(path, 'release.json'), 'utf8'));
+    return typeof metadata.version === 'string' && /^[\w.+-]+$/.test(metadata.version)
+      && ['linux-x64', 'macos-arm64', 'windows-x64'].includes(metadata.target)
+      && packageNames.includes(JSON.parse(readFileSync(join(path, 'app/package.json'), 'utf8')).name);
+  } catch { return false; }
+}
+
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+    'bin-dir': { type: 'string' }, 'release-root': { type: 'string' }, help: { type: 'boolean', short: 'h' },
+  } });
+  if (values.help) {
+    const metadata = join(root, 'release.json');
+    const target = inspect(metadata) ? JSON.parse(readFileSync(metadata, 'utf8')).target
+      : windows ? 'windows-x64' : process.platform === 'darwin' ? 'macos-arm64' : 'linux-x64';
+    const platform = target === 'windows-x64' ? 'Windows x64' : target === 'macos-arm64' ? 'macOS Apple silicon' : 'Linux x64';
+    const application = target === 'windows-x64' ? '%LOCALAPPDATA%\\Programs\\Outask'
+      : target === 'macos-arm64' ? '~/Library/Application Support/Outask' : '~/.local/share/outask';
+    const command = target === 'windows-x64' ? '%LOCALAPPDATA%\\Programs\\Outask\\commands\\outask.cmd' : '~/.local/bin/outask';
+    console.log(`Outask installer (${platform})
+Usage: ${target === 'windows-x64' ? './Install.cmd (PowerShell), Install.cmd (cmd.exe)' : `./${publicInstallers[target]}`} [install|update|uninstall] [--bin-dir <directory>] [--release-root <parent-directory>]
+Requires Node.js 22.23.3 or later on PATH. Open a new terminal after installation.
+${target === 'windows-x64' ? 'Before first using this Windows writer generation, finish writes and close all previous CLI/MCP/HTTP sessions. Start new writers afterward; do not mix generations.\n' : ''}Application: ${application}
+Command: ${command}
+Install from the extracted application directory. Update downloads GitHub Latest stable; tar and network access are required.
+Options change the command directory and application parent; reuse them for update/uninstall.
+Uninstall removes the managed command link; application files, projects and configuration remain.`);
+  } else {
+    if (positionals.length > 1 || !['install', 'update', 'uninstall'].includes(positionals[0] ?? 'install')
+      || values['bin-dir'] === '' || values['release-root'] === '') throw new Error('INVALID_INPUT: invalid action or empty directory');
+    const bin = canonical(resolve(values['bin-dir'] ?? defaults.bin));
+    const legacyRoot = canonical(join(homedir(), '.local/share/task-tracker/releases'));
+    const defaultRoot = defaults.releases;
+    const requestedRoot = canonical(resolve(values['release-root'] ?? defaultRoot));
+    const oldDefaults = legacyLocations().slice(0, 2).map(canonical);
+    // Old packaged updaters explicitly pass their former default directories.
+    // Recognise those defaults while preserving genuinely custom locations.
+    const releases = oldDefaults.includes(requestedRoot) ? canonical(defaultRoot) : requestedRoot;
+    if (!managed(root)) throw new Error('INVALID_RELEASE: invalid release metadata or application');
+    const releaseTarget = JSON.parse(readFileSync(join(root, 'release.json'), 'utf8')).target;
+    const payload = ['app', 'bin', publicInstallers[releaseTarget], 'release.json', 'README.md'];
+    const destination = join(releases, basename(defaults.destination));
+    const releaseRoots = [releases, legacyRoot, ...legacyLocations().map(canonical)];
+    const migration = positionals[0] === 'uninstall' ? undefined : legacyConfig();
+    if (positionals[0] !== 'uninstall' && migration && inspect(migration.target)
+      && !readFileSync(migration.source).equals(readFileSync(migration.target))) {
+      throw new Error(`CONFIG_CONFLICT: ${migration.source} and ${migration.target} differ; reconcile the registries before migrating`);
+    }
+    const targets = commandNames.map((name) => join(bin, windows ? `${name}.cmd` : name));
+    const target = targets[0];
+    function owned(path) {
+      if (windows) {
+        if (!inspect(path)?.isFile()) return false;
+        const entry = launcherEntry(readFileSync(path, 'utf8'));
+        if (!entry) return false;
+        const parent = resolve(entry, '../../..');
+        if (entry !== join(parent, 'app/bin/tasks')) return false;
+        if (managed(parent)) return releaseRoots.includes(dirname(parent));
+        if (inspect(join(parent, 'release.json'))) return false;
+        try {
+          return packageNames.includes(JSON.parse(readFileSync(join(parent, 'app/package.json'), 'utf8')).name)
+            && readFileSync(entry, 'utf8').includes("import('../cli.mjs')");
+        } catch { return false; }
+      }
+      if (!inspect(path)?.isSymbolicLink()) return false;
+      const linked = canonical(resolve(dirname(path), readlinkSync(path)));
+      const parent = linked.endsWith('/app/bin/tasks') ? resolve(linked, '../../..') : resolve(linked, '../..');
+      if (releaseRoots.includes(dirname(parent)) && managed(parent)) {
+        const metadata = JSON.parse(readFileSync(join(parent, 'release.json'), 'utf8'));
+        return linked === join(parent, 'app/bin/tasks') || linked === join(parent, 'bin/tasks');
+      }
+      if (linked !== join(parent, 'app/bin/tasks') || inspect(join(parent, 'release.json'))) return false;
+      try {
+        return packageNames.includes(JSON.parse(readFileSync(join(parent, 'app/package.json'), 'utf8')).name)
+          && readFileSync(linked, 'utf8').includes("import('../cli.mjs')");
+      } catch { return false; }
+    }
+    for (const target of targets) if (inspect(target) && !owned(target)) throw new Error(`COMMAND_EXISTS: ${target} is unrelated; resolve the collision before installing`);
+    if (positionals[0] === 'uninstall') {
+      for (const target of targets) if (owned(target)) unlinkSync(target);
+      console.log(`Removed managed command link at ${target}. Application copies, project data and configuration are preserved.`);
+    } else if (positionals[0] === 'update') {
+      const installed = [destination, ...targets.filter(owned).map((path) => windows ? resolve(launcherEntry(readFileSync(path, 'utf8')), '../../..') : resolve(realpathSync(path), '../../..'))].find(managed);
+      if (!installed) throw new Error('NOT_INSTALLED: install first, or reuse your original --bin-dir and --release-root');
+      await updateRelease({ destination: installed, bin, releases });
+    } else {
+      if (windows) console.log('Windows coordination: before first using this writer generation, finish active writes and close all prior CLI/MCP/HTTP sessions. Start new writers afterward; do not mix generations.');
+      const obsolete = obsoleteInstalls(releaseRoots, destination, managed);
+      accessSync(join(root, 'app/bin/tasks'), constants.X_OK);
+      await import('../cli.mjs');
+      for (const part of (process.env.PATH ?? '').split(delimiter)) {
+        for (const name of windows ? commandNames.flatMap((name) => ['.cmd', '.exe', '.bat', '.com', '.ps1', ''].map((extension) => name + extension)) : commandNames) {
+          const candidate = resolve(part || '.', name);
+          if (executable(candidate) && !targets.includes(canonical(candidate)) && !owned(candidate)) throw new Error(`COMMAND_EXISTS: ${candidate} is already on PATH; resolve the collision before installing`);
+        }
+      }
+      const stateOnly = destination === canonical(defaults.destination) && inspect(destination)?.isDirectory()
+        && readdirSync(destination).every(name => ['config.json', 'cache', 'locks', 'commands'].includes(name));
+      if (inspect(destination) && (!inspect(destination).isDirectory() || (!managed(destination) && !stateOnly))) {
+        throw new Error(`INSTALL_EXISTS: ${destination} is unrelated; choose another --release-root or resolve the collision`);
+      }
+      // Stage the new program separately; unrelated files beside it are retained.
+      mkdirSync(releases, { recursive: true });
+      const work = mkdtempSync(join(releases, '.outask-install-'));
+      const staged = join(work, 'new');
+      const backup = join(work, 'old');
+      let linkWork;
+      let committed = false;
+      let rollbackFailed = false;
+      try {
+        mkdirSync(staged);
+        for (const name of payload) {
+          if (inspect(join(root, name))) cpSync(join(root, name), join(staged, name), copyOptions);
+        }
+        const check = spawnSync(process.execPath, [join(staged, 'app/bin/tasks'), '--help'], { encoding: 'utf8', timeout: 60000 });
+        if (check.error) throw check.error;
+        if (check.status !== 0) {
+          const entry = join(staged, 'app/bin/tasks');
+          const details = { source: startupFile(join(root, 'app/bin/tasks')), staged: startupFile(entry) };
+          try {
+            const names = readdirSync(dirname(entry));
+            details.binNames = names.slice(0, 32);
+            details.binNamesTruncated = names.length > 32;
+          } catch (error) { details.binError = error.code; }
+          // Probe through the child runtime's filesystem API independently of its main-module resolver.
+          const probe = spawnSync(process.execPath, ['-e', `const { lstatSync, realpathSync, readFileSync } = require('node:fs'); ${startupFile.toString()}; console.log(JSON.stringify(startupFile(process.argv[1])));`, entry], { encoding: 'utf8', timeout: 10000 });
+          details.child = { status: probe.status, error: probe.error?.code };
+          try { details.child.file = JSON.parse(probe.stdout); } catch { details.child.stderr = (probe.stderr ?? '').slice(0, 500); }
+          throw new Error(`INVALID_RELEASE: staged application failed startup: ${check.stderr || check.stdout}\nStaged startup diagnostics: ${JSON.stringify(details)}`);
+        }
+        const commandsInside = bin === destination || bin.startsWith(destination + sep);
+        if (!commandsInside) mkdirSync(bin, { recursive: true });
+        linkWork = mkdtempSync(join(commandsInside ? releases : bin, '.outask-link-'));
+        for (const [index, target] of targets.entries()) {
+          const link = join(linkWork, `new-${index}`);
+          if (windows) writeFileSync(link, windowsLauncher(join(destination, 'app/bin/tasks')));
+          else symlinkSync(join(destination, 'app/bin/tasks'), link);
+        }
+        const swapped = [];
+        mkdirSync(destination, { recursive: true });
+        mkdirSync(backup);
+        try {
+          // The root and all persistent state retain their original inodes.
+          for (const name of managedPayload) {
+            const current = join(destination, name);
+            const replacement = join(staged, name);
+            if (inspect(current)?.isFile() && inspect(replacement)?.isFile()
+              && readFileSync(current).equals(readFileSync(replacement))) continue;
+            const item = { name, previous: false, installed: false };
+            swapped.push(item);
+            if (inspect(current)) {
+              renameSync(current, join(backup, name));
+              item.previous = true;
+            }
+            if (inspect(replacement)) {
+              renameSync(replacement, current);
+              item.installed = true;
+            }
+          }
+          mkdirSync(bin, { recursive: true });
+          for (const [index, target] of targets.entries()) {
+            if (inspect(target)) cpSync(target, join(linkWork, `old-${index}`), copyOptions);
+            renameSync(join(linkWork, `new-${index}`), target);
+          }
+          committed = true;
+        } catch (error) {
+          for (const item of swapped.reverse()) {
+            try {
+              if (item.installed) renameSync(join(destination, item.name), join(staged, item.name));
+              if (item.previous) renameSync(join(backup, item.name), join(destination, item.name));
+            } catch (restoreError) {
+              rollbackFailed = true;
+              console.error(`Application recovery files retained at ${work}: ${restoreError.message}`);
+            }
+          }
+          for (const [index, target] of targets.entries()) {
+            if (inspect(join(linkWork, `new-${index}`))) continue;
+            try {
+              if (inspect(target)) unlinkSync(target);
+              if (inspect(join(linkWork, `old-${index}`))) cpSync(join(linkWork, `old-${index}`), target, copyOptions);
+            } catch (restoreError) {
+              rollbackFailed = true;
+              console.error(`Command backup retained at ${linkWork}: ${restoreError.message}`);
+            }
+          }
+          throw error;
+        }
+      } finally {
+        // Retain a backup if an OS error prevents rollback, rather than deleting it.
+        if (committed || !rollbackFailed) rmSync(work, { recursive: true, force: true });
+        else console.error(`Recovery files retained at ${work}`);
+        if (linkWork && !rollbackFailed) rmSync(linkWork, { recursive: true, force: true });
+      }
+      retireConfig(migration);
+      for (const previous of obsolete) retirePayload(previous, managedPayload);
+      console.log(`Installed Outask at ${destination}. Commands: ${targets.join(', ')}`);
+      for (const message of configurePath(bin)) console.log(message);
+    }
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/lifecycle.mjs

@@ -0,0 +1,35 @@
+import { parseArgs } from 'node:util';
+import { deleteTask, transitionTask } from '../src/transition.mjs';
+import { fail } from '../src/errors.mjs';
+import { parseInteger, parseProject, parseSchema, projectHelp } from './arguments.mjs';
+import { checkOptions } from './task-write-input.mjs';
+import { reportError } from './output.mjs';
+
+export function lifecycleCommand(deleting) {
+  const command = deleting ? 'delete-task' : 'transition-task';
+  const statusUsage = deleting ? '[--status <Archive-status>] ' : '--status <status> ';
+  const usage = `Usage: node app/scripts/${command}.mjs [project-path] <id> ${statusUsage}[--store <name>] [--if-updated-at <timestamp>] [--format json]`;
+  const options = {
+    'if-updated-at': { type: 'string' }, store: { type: 'string' },
+    status: { type: 'string' },
+    'schema-path': { type: 'string' },
+    format: { type: 'string', default: 'json' }, help: { type: 'boolean', short: 'h' },
+  };
+  const help = `${usage}\n${projectHelp}Move one retained task and return the complete task as JSON. --if-updated-at optionally checks the exact current timestamp under the write lock.\n${deleting ? 'Delete retains the task in Archive; choose --status when several Archive statuses exist.' : 'Any configured status is allowed; use an Active status to restore retained history.'}\nActual changes advance updated_at; no-ops preserve it. --if-updated-at expects a canonical UTC millisecond value, e.g. 2026-09-19T12:00:00.000Z.\nUnknown --status values report configured status choices. Status names are case-sensitive.\nConfigured destination files must exist. Use --store for ambiguous destinations. --schema-path selects a project-relative schema file. Run validation to recover interrupted moves.\n`;
+  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 settings = { ifUpdatedAt: values['if-updated-at'], store: values.store, schemaPath: parseSchema(values, tokens) };
+    const result = deleting ? deleteTask(project, parseInteger(id, 'id', 1), { ...settings, status: values.status })
+      : transitionTask(project, parseInteger(id, 'id', 1), values.status, settings);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+  return { usage, options, help, main };
+}
+
+export function runLifecycle(deleting) {
+  try { lifecycleCommand(deleting).main(process.argv.slice(2)); } catch (error) { reportError(error); }
+}

package/scripts/list-tasks.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { fail } from '../src/errors.mjs';
+import { defaultLimit, maxLimit, responseBytes } from '../src/limits.mjs';
+import { updatePage } from '../src/pagination.mjs';
+import { textBuffer } from '../src/response.mjs';
+import { countTasks, listTasks } from '../src/tasks.mjs';
+import { cacheOptions, commonHelp, commonOptions, parseInteger, parseOutput, parseProject, parseSchema, parseSelection, projectHelp } from './arguments.mjs';
+import { isMain } from './entry.mjs';
+import { nextCommand } from './continuation.mjs';
+import { formatOutput, printOutput, reportError } from './output.mjs';
+
+export const options = {
+  ...commonOptions,
+  format: { type: 'string' }, full: { type: 'boolean' },
+  where: { type: 'string', multiple: true }, status: { type: 'string' },
+  id: { type: 'string', multiple: true }, sort: { type: 'string', default: 'id' },
+  desc: { type: 'boolean', default: false }, limit: { type: 'string', default: String(defaultLimit) },
+  offset: { type: 'string', default: '0' }, count: { type: 'boolean', default: false },
+};
+export const usage = 'Usage: node app/scripts/list-tasks.mjs [project-path] [options]';
+export const help = `${usage}
+
+${projectHelp}Reads never change task files.
+  --fields <names>     Comma-separated fields; id,title,status (default), or all
+  --full              All fields; text unless --format is supplied; excludes --fields/ids
+${commonHelp.replace('text (default), table, json or ids', 'table (default), text, json or ids')}  --status <status>   Exact, case-sensitive status filter
+  --where <field>=<value>  Repeatable AND filters; status is exact
+  --id <id>           Repeatable ID filter (OR within IDs)
+  --sort <field>      id (default); priority orders high, medium, low
+  --desc             Reverse primary sort; ties always use ascending ID
+  --limit <n>         Page size from 1 to 50 (default: 10); responses up to 32 KiB
+  --offset <n>        Skip matching records (default: 0)
+  --count            Print match count, ignoring pagination
+`;
+
+function parseFilters(values) {
+  const filters = (values.where ?? []).map((expression) => {
+    const separator = expression.indexOf('=');
+    if (separator < 1) fail('INVALID_INPUT', '--where expects <field>=<value>');
+    return { field: expression.slice(0, separator), value: expression.slice(separator + 1) };
+  });
+  if (values.status !== undefined) filters.push({ field: 'status', value: values.status });
+  return filters;
+}
+
+function parseQuery(values) {
+  return {
+    ...parseSelection(values), filters: parseFilters(values),
+    ids: (values.id ?? []).map((id) => parseInteger(id, '--id', 1)),
+    sort: values.sort, descending: values.desc,
+    limit: parseInteger(values.limit, '--limit', 1, maxLimit), offset: parseInteger(values.offset, '--offset'),
+    refreshMode: 'detached',
+    ...cacheOptions(values),
+  };
+}
+
+function pageInfo(page, args, tokens, invocation) {
+  const range = page.tasks.length ? `records ${page.offset + 1}-${page.offset + page.tasks.length}` : 'no records';
+  const buffer = textBuffer();
+  buffer.add(`Showing ${range} of ${page.total} matches.\n`);
+  if (page.hasMore) {
+    const command = nextCommand(args, tokens, 'offset', page.nextOffset, 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') {
+    printOutput(page, page.fields, output);
+    return;
+  }
+  while (true) {
+    const info = pageInfo(page, args, tokens, invocation);
+    if (info === undefined) fail('OUTPUT_TOO_LARGE', 'page guidance exceeds 32 KiB; shorten field selections or filters');
+    const text = formatOutput(page.tasks, page.fields, output, responseBytes - Buffer.byteLength(info, 'utf8'));
+    if (text !== undefined) {
+      process.stdout.write(text);
+      process.stderr.write(info);
+      return;
+    }
+    if (page.tasks.length <= 1) {
+      fail('OUTPUT_TOO_LARGE', 'first task cannot fit in a rendered 32 KiB page; select fewer --fields, a smaller --max-width or shorter filters');
+    }
+    page.tasks.pop();
+    updatePage(page);
+  }
+}
+
+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 } = parseProject(positionals, usage);
+  if (values.full && (values.fields !== undefined || values.format === 'ids')) {
+    fail('INVALID_INPUT', '--full cannot be combined with --fields or --format ids');
+  }
+  values.format ??= values.full ? 'text' : 'table';
+  if (values.full) values.fields = 'all';
+  const output = parseOutput(values);
+  const query = parseQuery(values);
+  query.schemaPath = parseSchema(values, tokens);
+  if (values.count) process.stdout.write(`${countTasks(project, query)}\n`);
+  else showPage(listTasks(project, query), output, guidance?.args ?? args, guidance?.tokens ?? tokens, guidance?.invocation);
+}
+
+if (isMain(import.meta.url)) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    reportError(error);
+  }
+}