praxis-agent 0.42.1 → 0.43.0

package/README.md

@@ -45,6 +45,7 @@ praxis --version
 
 Release tarballs, SBOMs, SHA-256 checksums, and build attestations are attached
 to every [GitHub release](https://github.com/Forest-Isle/Praxis/releases).
+Use `praxis update` for transactional self-updates; see [Getting Started](https://github.com/Forest-Isle/Praxis/blob/main/docs/GETTING_STARTED.md) for recovery and verification details.
 
 ## Quick start
 
@@ -204,6 +205,9 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
 - **Provider-neutral models** — native Anthropic Messages and OpenAI-compatible
   streaming adapters with explicit capability checks, metering controls, and
   a bounded absolute deadline for every provider attempt.
+- **Transactional self-update** — `praxis update` verifies the package before
+  installing it, rejects concurrent updates, and can roll back after an
+  interruption or crash.
 
 Detailed feature status and executable evidence live in the
 [parity matrix](https://github.com/Forest-Isle/Praxis/blob/main/docs/PARITY_MATRIX.md),

package/dist/cli-runtime.d.ts

@@ -174,6 +174,7 @@ export interface CliDependencies extends InteractiveServiceFactory {
         operation: 'install' | 'update';
         target?: string;
         force?: boolean;
+        signal?: AbortSignal;
     }) => Promise<SelfUpdateResult>;
 }
 /**

package/dist/cli-runtime.js

@@ -2788,7 +2788,7 @@ async function executeDoctorCommand(args, invocation, io) {
     }
     return report.ok ? 0 : 1;
 }
-async function executeSelfUpdateCommand(argv, io, dependencies) {
+async function executeSelfUpdateCommand(argv, io, dependencies, signal) {
     const command = argv[0];
     const values = [];
     for (let index = 1; index < argv.length; index += 1) {
@@ -2812,6 +2812,7 @@ async function executeSelfUpdateCommand(argv, io, dependencies) {
         const runtimeSettings = await loadRuntimeSettings({ configRoot, statePath });
         const result = await dependencies.selfUpdate?.({
             operation: 'update',
+            ...(signal ? { signal } : {}),
             ...(runtimeSettings.autoUpdatesChannel === 'latest'
                 ? {}
                 : { target: runtimeSettings.autoUpdatesChannel }),
@@ -2836,6 +2837,7 @@ async function executeSelfUpdateCommand(argv, io, dependencies) {
         throw new Error('install accepts at most one target');
     const result = await dependencies.selfUpdate?.({
         operation: 'install',
+        ...(signal ? { signal } : {}),
         force,
         ...(targets[0] === undefined ? {} : { target: targets[0] }),
     });
@@ -4600,7 +4602,7 @@ async function execute(argv, io, dependencies, signal) {
         return executeProjectPurgeCommand(['project', 'purge', ...prefixedPurgeOptions, ...special.args.slice(2)], io);
     }
     if (['install', 'update', 'upgrade'].includes(special.args[0] ?? '')) {
-        return executeSelfUpdateCommand([special.args[0], ...special.args.slice(1)], io, dependencies);
+        return executeSelfUpdateCommand([special.args[0], ...special.args.slice(1)], io, dependencies, signal);
     }
     if (printCommandHelp(argv, io))
         return 0;

package/dist/maintenance/self-update-transaction.d.ts

@@ -0,0 +1,39 @@
+export interface SelfUpdateLayout {
+    packageRoot: string;
+    globalNodeModulesRoot: string;
+    globalPrefix: string;
+    binPath: string;
+}
+export interface TransactionRunnerOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+    maxBuffer?: number;
+    signal?: AbortSignal;
+}
+export type TransactionRunner = (executable: string, args: readonly string[], options: TransactionRunnerOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export interface SelfUpdateTransactionOptions {
+    packageName: string;
+    target: string;
+    force: boolean;
+    npmExecutable: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    run: TransactionRunner;
+    layout?: SelfUpdateLayout;
+}
+export interface SelfUpdateTransactionResult {
+    output: string;
+}
+/** Transactional updater implementation. */
+export declare function runSelfUpdateTransaction(options: SelfUpdateTransactionOptions): Promise<SelfUpdateTransactionResult>;
+export declare function generateLauncherSource(layout: SelfUpdateLayout, lockPath: string, journal: string): string;
+export declare function validateSelfUpdateLayout(layout: SelfUpdateLayout): SelfUpdateLayout;
+export declare function checksum(bytes: Uint8Array): {
+    sha1: string;
+    sha512: string;
+};
+//# sourceMappingURL=self-update-transaction.d.ts.map

package/dist/maintenance/self-update-transaction.js

@@ -0,0 +1,356 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { access, chmod, mkdir, mkdtemp, open, readFile, rename, rm, stat, symlink, } from 'node:fs/promises';
+import { dirname, basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
+/** Transactional updater implementation. */
+export async function runSelfUpdateTransaction(options) {
+    if (process.platform === 'win32')
+        throw new Error('self-update is unsupported on Windows');
+    options.signal?.throwIfAborted();
+    const layout = validateSelfUpdateLayout(options.layout ?? deriveLayout());
+    if (layout.packageRoot !==
+        join(layout.globalNodeModulesRoot, options.packageName))
+        throw new Error('current package is not installed in the requested global layout');
+    const parent = dirname(layout.packageRoot);
+    const lockPath = `${layout.packageRoot}.update.lock`;
+    let owner;
+    try {
+        owner = await new ExclusiveFileLease(lockPath).tryAcquire();
+    }
+    catch (error) {
+        throw normalizeTransactionError(error);
+    }
+    if (!owner)
+        throw new Error('Praxis update already in progress');
+    let backup = '';
+    let staging = '';
+    const journal = `${layout.packageRoot}.update.journal`;
+    try {
+        await validateCandidate(layout.packageRoot, options.packageName);
+        options.signal?.throwIfAborted();
+        const spec = `${options.packageName}@${options.target}`;
+        const view = await options.run(options.npmExecutable, ['view', spec, 'version', 'dist', '--json'], runnerOptions(options));
+        const metadata = parseView(view.stdout, options.packageName);
+        staging = await mkdtemp(join(parent, '.praxis-update-'));
+        await chmod(staging, 0o700);
+        const download = join(staging, 'download');
+        await mkdir(download, { recursive: true, mode: 0o700 });
+        await chmod(download, 0o700);
+        const packed = await options.run(options.npmExecutable, [
+            'pack',
+            spec,
+            '--ignore-scripts',
+            '--json',
+            '--pack-destination',
+            download,
+        ], runnerOptions(options));
+        const pack = parsePack(packed.stdout, metadata, download, options.packageName);
+        const bytes = await readFile(pack.path);
+        const sums = checksum(bytes);
+        if (sums.sha512 !== metadata.integrity || sums.sha1 !== metadata.shasum)
+            throw new Error('package integrity/checksum mismatch');
+        const stagingPrefix = join(staging, 'prefix');
+        await mkdir(stagingPrefix, { recursive: true, mode: 0o700 });
+        await chmod(stagingPrefix, 0o700);
+        const installArgs = [
+            'install',
+            '--global',
+            '--prefix',
+            stagingPrefix,
+            '--no-fund',
+            '--no-audit',
+            '--ignore-scripts',
+            ...(options.force ? ['--force'] : []),
+            pack.path,
+        ];
+        await options.run(options.npmExecutable, installArgs, runnerOptions(options));
+        const candidate = join(stagingPrefix, 'lib', 'node_modules', options.packageName);
+        await validateCandidate(candidate, options.packageName, metadata.version);
+        await gate(options, join(candidate, 'dist', 'cli.js'), metadata.version);
+        options.signal?.throwIfAborted();
+        backup = `${layout.packageRoot}.update-backup-${randomUUID()}`;
+        await installLauncher(layout, lockPath, journal);
+        await writeJournal(journal, {
+            version: 1,
+            root: layout.packageRoot,
+            backup,
+            staging,
+            targetVersion: metadata.version,
+            phase: 'prepared',
+        });
+        await rename(layout.packageRoot, backup);
+        await rename(candidate, layout.packageRoot);
+        await syncDirectory(parent);
+        await writeJournal(journal, {
+            version: 1,
+            root: layout.packageRoot,
+            backup,
+            staging,
+            targetVersion: metadata.version,
+            phase: 'candidate',
+        });
+        await gate(options, join(layout.packageRoot, 'dist', 'cli.js'), metadata.version);
+        await cleanupCompletedTransaction(backup, staging, journal);
+        return { output: 'completed' };
+    }
+    catch (error) {
+        const failure = normalizeTransactionError(error);
+        if (backup) {
+            try {
+                await rollback(layout.packageRoot, backup, staging, journal);
+            }
+            catch (recovery) {
+                const recoveryFailure = normalizeTransactionError(recovery);
+                throw new Error(`${failure instanceof Error ? failure.message : String(failure)}; recovery failed: ${recoveryFailure instanceof Error ? recoveryFailure.message : String(recoveryFailure)}`, { cause: failure });
+            }
+        }
+        else if (staging)
+            await cleanupCompletedTransaction('', staging, journal);
+        throw failure;
+    }
+    finally {
+        await releaseLease(owner);
+    }
+}
+function deriveLayout() {
+    const packageRoot = resolve(process.env.PRAXIS_SELF_UPDATE_ROOT ??
+        dirname(fileURLToPath(import.meta.url)), process.env.PRAXIS_SELF_UPDATE_ROOT ? '.' : '../..');
+    const globalNodeModulesRoot = dirname(packageRoot);
+    const globalPrefix = dirname(dirname(globalNodeModulesRoot));
+    return {
+        packageRoot,
+        globalNodeModulesRoot,
+        globalPrefix,
+        binPath: join(globalPrefix, 'bin', 'praxis'),
+    };
+}
+function runnerOptions(options) {
+    return {
+        env: process.env,
+        timeout: options.timeoutMs,
+        maxBuffer: 4 * 1024 * 1024,
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('invalid npm metadata');
+    }
+}
+function semver(value) {
+    return (typeof value === 'string' &&
+        /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.test(value));
+}
+function parseView(text, name) {
+    const value = parseJson(text);
+    const dist = value.dist;
+    if (!semver(value.version) ||
+        !dist ||
+        typeof dist.tarball !== 'string' ||
+        !/^https:\/\//u.test(dist.tarball) ||
+        typeof dist.integrity !== 'string' ||
+        !/^sha512-[A-Za-z0-9+/]+=*$/u.test(dist.integrity) ||
+        typeof dist.shasum !== 'string' ||
+        !/^[0-9a-f]{40}$/iu.test(dist.shasum))
+        throw new Error(`invalid metadata for ${name}`);
+    return {
+        version: value.version,
+        integrity: dist.integrity,
+        shasum: dist.shasum.toLowerCase(),
+        tarball: dist.tarball,
+    };
+}
+function parsePack(text, metadata, dir, packageName) {
+    const value = parseJson(text);
+    if (!Array.isArray(value) || value.length !== 1)
+        throw new Error('invalid npm pack metadata');
+    const record = value[0];
+    if (record.version !== metadata.version ||
+        record.name !== packageName ||
+        record.integrity !== metadata.integrity ||
+        String(record.shasum).toLowerCase() !== metadata.shasum ||
+        typeof record.filename !== 'string' ||
+        basename(record.filename) !== record.filename ||
+        !record.filename.endsWith('.tgz'))
+        throw new Error('npm pack metadata mismatch');
+    return { path: join(dir, record.filename) };
+}
+async function validateCandidate(root, name, expectedVersion) {
+    const manifest = parseJson(await readFile(join(root, 'package.json'), 'utf8'));
+    const cli = await stat(join(root, 'dist', 'cli.js'));
+    if (manifest.name !== name ||
+        !semver(manifest.version) ||
+        (expectedVersion !== undefined && manifest.version !== expectedVersion) ||
+        !cli.isFile())
+        throw new Error('staged package validation failed');
+    return manifest.version;
+}
+async function gate(options, cli, version) {
+    const result = await options.run(process.execPath, [cli, '--version'], runnerOptions(options));
+    if (result.stdout.trim() !== version)
+        throw new Error('candidate version gate failed');
+}
+async function writeJournal(path, value) {
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(tmp, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(value));
+            await handle.chmod(0o600);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmp, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await rm(tmp, { force: true });
+    }
+}
+async function rollback(root, backup, staging, journal) {
+    if (await exists(backup)) {
+        let failed = '';
+        if (await exists(root)) {
+            failed = join(staging, 'failed-candidate');
+            await rename(root, failed);
+        }
+        await rename(backup, root);
+        await syncDirectory(dirname(root));
+        if (failed)
+            await rm(failed, { recursive: true, force: true });
+    }
+    else if (!(await exists(root))) {
+        throw new Error('update backup is unavailable');
+    }
+    await cleanupCompletedTransaction('', staging, journal);
+}
+async function cleanupCompletedTransaction(backup, staging, journal) {
+    try {
+        if (backup)
+            await rm(backup, { recursive: true, force: true });
+        if (staging)
+            await rm(staging, { recursive: true, force: true });
+        await rm(journal, { force: true });
+        await syncDirectory(dirname(journal));
+    }
+    catch {
+        // The external launcher retries validated cleanup once the lease is gone.
+    }
+}
+async function syncDirectory(path) {
+    const handle = await open(path, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeTransactionError(error) {
+    if (typeof error !== 'object' || error === null)
+        return error;
+    const systemError = error;
+    if (typeof systemError.path === 'string' ||
+        typeof systemError.dest === 'string' ||
+        typeof systemError.syscall === 'string') {
+        return new Error('self-update filesystem transaction failed', {
+            cause: error,
+        });
+    }
+    return error;
+}
+async function releaseLease(owner) {
+    try {
+        await owner.release();
+    }
+    catch (error) {
+        throw normalizeTransactionError(error);
+    }
+}
+async function installLauncher(layout, lockPath, journal) {
+    const launcher = `${layout.packageRoot}.launcher.mjs`;
+    const source = generateLauncherSource(layout, lockPath, journal);
+    const tmp = `${launcher}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(tmp, 'wx', 0o700);
+        try {
+            await handle.writeFile(source);
+            await handle.chmod(0o700);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(tmp, launcher);
+        await syncDirectory(dirname(launcher));
+        const link = `${layout.binPath}.${randomUUID()}.tmp`;
+        try {
+            await symlink(launcher, link);
+            await rename(link, layout.binPath);
+            await syncDirectory(dirname(layout.binPath));
+        }
+        finally {
+            await rm(link, { force: true });
+        }
+    }
+    finally {
+        await rm(tmp, { force: true });
+    }
+}
+export function generateLauncherSource(layout, lockPath, journal) {
+    return `#!/usr/bin/env node
+import { existsSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const root=${JSON.stringify(layout.packageRoot)}, parent=${JSON.stringify(dirname(layout.packageRoot))}, backupPrefix=${JSON.stringify(`${layout.packageRoot}.update-backup-`)}, stagingPrefix=${JSON.stringify(`${dirname(layout.packageRoot)}/.praxis-update-`)}, lock=${JSON.stringify(lockPath)}, journal=${JSON.stringify(journal)};
+const alive=(p)=>{try{process.kill(p,0);return true}catch(e){return e.code==='EPERM'}};
+const owner=()=>{try{const j=JSON.parse(readFileSync(lock,'utf8'));return j&&j.version===1&&Number.isSafeInteger(j.pid)&&j.pid>0&&typeof j.token==='string'&&/^[A-Za-z0-9_-]{1,128}$/.test(j.token)&&typeof j.createdAt==='string'&&alive(j.pid)}catch{return false}};
+const sibling=(value,prefix)=>typeof value==='string'&&value===resolve(value)&&dirname(value)===parent&&value.startsWith(prefix)&&value.length>prefix.length;
+const valid=(j)=>j&&j.version===1&&j.root===root&&sibling(j.backup,backupPrefix)&&sibling(j.staging,stagingPrefix)&&['prepared','backup','candidate'].includes(j.phase)&&typeof j.targetVersion==='string';
+const liveOwner=owner();
+if(liveOwner&&!existsSync(root)){let n=0;while(n++<20&&!existsSync(root)){await new Promise(r=>setTimeout(r,25))}if(!existsSync(root))throw new Error('Praxis update already in progress');
+} else if(!liveOwner&&existsSync(journal)){const j=JSON.parse(readFileSync(journal,'utf8'));if(!valid(j))throw new Error('invalid update journal');if(!existsSync(root)&&existsSync(j.backup))renameSync(j.backup,root);if(existsSync(root)){if(existsSync(j.backup))rmSync(j.backup,{recursive:true,force:true});rmSync(j.staging,{recursive:true,force:true});rmSync(journal,{force:true});}}
+if(!existsSync(root)) throw new Error('Praxis update recovery failed');
+process.env.PRAXIS_SELF_UPDATE_ROOT=root; const controller=new AbortController(); const cancel=()=>controller.abort(); process.on('SIGINT',cancel); process.on('SIGTERM',cancel); try { const mod=await import(join(root,'dist','cli.js')); if(typeof mod.run!=='function') throw new Error('CLI entrypoint unavailable'); process.exitCode=await mod.run(process.argv.slice(2),undefined,undefined,controller.signal); } finally { process.removeListener('SIGINT',cancel); process.removeListener('SIGTERM',cancel); }
+`;
+}
+export function validateSelfUpdateLayout(layout) {
+    const packageRoot = resolve(layout.packageRoot);
+    const modules = resolve(layout.globalNodeModulesRoot);
+    const prefix = resolve(layout.globalPrefix);
+    const binPath = resolve(layout.binPath);
+    if (dirname(packageRoot) !== modules ||
+        dirname(modules) !== join(prefix, 'lib')) {
+        throw new Error('unsupported global npm installation layout');
+    }
+    if (binPath !== join(prefix, 'bin', 'praxis')) {
+        throw new Error('unsupported global npm bin layout');
+    }
+    return {
+        packageRoot,
+        globalNodeModulesRoot: modules,
+        globalPrefix: prefix,
+        binPath,
+    };
+}
+export function checksum(bytes) {
+    return {
+        sha1: createHash('sha1').update(bytes).digest('hex'),
+        sha512: `sha512-${createHash('sha512').update(bytes).digest('base64')}`,
+    };
+}
+//# sourceMappingURL=self-update-transaction.js.map

package/dist/maintenance/self-update.d.ts

@@ -1,3 +1,4 @@
+import { type SelfUpdateLayout } from './self-update-transaction.js';
 export type SelfUpdateOperation = 'install' | 'update';
 export interface SelfUpdateOptions {
     operation: SelfUpdateOperation;
@@ -6,6 +7,8 @@ export interface SelfUpdateOptions {
     packageName?: string;
     npmExecutable?: string;
     timeoutMs?: number;
+    signal?: AbortSignal;
+    layout?: SelfUpdateLayout;
     run?: SelfUpdateRunner;
 }
 export interface SelfUpdateRunnerOptions {
@@ -13,6 +16,7 @@ export interface SelfUpdateRunnerOptions {
     env?: NodeJS.ProcessEnv;
     timeout?: number;
     maxBuffer?: number;
+    signal?: AbortSignal;
 }
 export type SelfUpdateRunner = (executable: string, args: readonly string[], options: SelfUpdateRunnerOptions) => Promise<{
     stdout: string;

package/dist/maintenance/self-update.js

@@ -1,20 +1,27 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { runSelfUpdateTransaction, } from './self-update-transaction.js';
 const execFileAsync = promisify(execFile);
 const DEFAULT_PACKAGE_NAME = 'praxis-agent';
 const DEFAULT_TIMEOUT_MS = 120_000;
-const MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 const runCommand = async (executable, args, options) => {
-    const result = await execFileAsync(executable, [...args], {
-        cwd: options.cwd,
-        env: options.env,
-        timeout: options.timeout,
-        maxBuffer: options.maxBuffer,
-    });
-    return {
-        stdout: String(result.stdout ?? ''),
-        stderr: String(result.stderr ?? ''),
-    };
+    try {
+        const result = await execFileAsync(executable, [...args], {
+            cwd: options.cwd,
+            env: options.env,
+            timeout: options.timeout,
+            maxBuffer: options.maxBuffer,
+            signal: options.signal,
+        });
+        return {
+            stdout: String(result.stdout ?? ''),
+            stderr: String(result.stderr ?? ''),
+        };
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        throw new Error('self-update subprocess failed', { cause: error });
+    }
 };
 function validPackageName(value) {
     return /^(?:@[^/\s]+\/)?[^/\s]+$/u.test(value);
@@ -30,10 +37,6 @@ function requireTarget(value) {
     }
     return target;
 }
-function commandOutput(stdout, stderr) {
-    const output = `${stdout.trim()}${stderr.trim() ? `\n${stderr.trim()}` : ''}`;
-    return output.length > 0 ? output : 'completed';
-}
 export async function runSelfUpdate(options) {
     const packageName = options.packageName ?? DEFAULT_PACKAGE_NAME;
     if (!validPackageName(packageName)) {
@@ -56,10 +59,16 @@ export async function runSelfUpdate(options) {
     const runner = options.run ?? runCommand;
     let result;
     try {
-        result = await runner(npmExecutable, args, {
-            env: process.env,
-            timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-            maxBuffer: MAX_OUTPUT_BYTES,
+        const transactionRunner = runner;
+        result = await runSelfUpdateTransaction({
+            packageName,
+            target,
+            force,
+            npmExecutable,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            run: transactionRunner,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.layout ? { layout: options.layout } : {}),
         });
     }
     catch (error) {
@@ -75,7 +84,7 @@ export async function runSelfUpdate(options) {
         target,
         force,
         command: [npmExecutable, ...args],
-        output: commandOutput(result.stdout, result.stderr),
+        output: result.output,
     };
 }
 //# sourceMappingURL=self-update.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.42.1",
+  "version": "0.43.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",