@spexcode/session-selflaunch 0.6.8

package/bin/spex-session.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli.js'
+
+process.exitCode = await runCli()

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+import type { SessionProtocol } from '@spexcode/session-protocol';
+import type { SelfLaunchEnvironment } from './path.js';
+type CommandName = 'initialize' | 'enqueue' | 'dequeue' | 'pending';
+interface ParsedCommand {
+    readonly command: CommandName;
+    readonly values: ReadonlyMap<string, string>;
+    readonly headers: readonly [string, string][];
+    readonly assumeLocal: boolean;
+}
+export declare function parseCommand(argv: readonly string[]): ParsedCommand;
+interface CliDependencies {
+    readonly open: (databasePath: string) => SessionProtocol;
+    readonly requireLocal: (databasePath: string, options: {
+        assumeLocal?: boolean;
+    }) => string;
+}
+export interface CliRunOptions {
+    readonly argv?: readonly string[];
+    readonly env?: SelfLaunchEnvironment;
+    readonly stdout?: (text: string) => void;
+    readonly stderr?: (text: string) => void;
+    readonly dependencies?: CliDependencies;
+}
+export declare function runCli(options?: CliRunOptions): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,156 @@
+import { LocalityError, requireLocalDatabasePath } from './locality.js';
+import { DatabasePathError, resolveDatabasePath } from './path.js';
+class UsageError extends Error {
+    code = 'USAGE';
+}
+const VALUE_FLAGS = {
+    initialize: new Set(['session-id', 'database-path']),
+    enqueue: new Set(['session-id', 'kind', 'body', 'sender-session-id', 'idempotency-key', 'database-path']),
+    dequeue: new Set(['session-id', 'database-path']),
+    pending: new Set(['session-id', 'database-path']),
+};
+const usage = () => {
+    throw new UsageError('usage: spex-session initialize|enqueue|dequeue|pending --session-id ID [command options]');
+};
+const isCommandName = (value) => (value === 'initialize' || value === 'enqueue' || value === 'dequeue' || value === 'pending');
+export function parseCommand(argv) {
+    const command = argv[0];
+    if (!isCommandName(command))
+        return usage();
+    const commandName = command;
+    const values = new Map();
+    const headers = [];
+    let assumeLocal = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--assume-local-storage') {
+            if (assumeLocal)
+                throw new UsageError('duplicate --assume-local-storage');
+            assumeLocal = true;
+            continue;
+        }
+        if (!token.startsWith('--'))
+            throw new UsageError(`unexpected argument ${token}`);
+        const name = token.slice(2);
+        if (name === 'header' && commandName === 'enqueue') {
+            const raw = argv[++index];
+            if (raw === undefined)
+                throw new UsageError('missing value for --header');
+            const separator = raw.indexOf('=');
+            if (separator <= 0)
+                throw new UsageError('--header must be K=V');
+            headers.push([raw.slice(0, separator), raw.slice(separator + 1)]);
+            continue;
+        }
+        if (!VALUE_FLAGS[commandName].has(name))
+            throw new UsageError(`unknown option --${name}`);
+        if (values.has(name))
+            throw new UsageError(`duplicate --${name}`);
+        const value = argv[++index];
+        if (value === undefined)
+            throw new UsageError(`missing value for --${name}`);
+        values.set(name, value);
+    }
+    if (!values.has('session-id'))
+        throw new UsageError('missing --session-id');
+    if (commandName === 'enqueue' && !values.has('kind'))
+        throw new UsageError('missing --kind');
+    if (commandName === 'enqueue' && !values.has('body'))
+        throw new UsageError('missing --body');
+    return { command: commandName, values, headers, assumeLocal };
+}
+const renderMessage = (message) => {
+    const { body, ...fields } = message;
+    return { ...fields, bodyBase64: Buffer.from(body).toString('base64') };
+};
+const errorCode = (error) => {
+    if (error instanceof UsageError)
+        return error.code;
+    if (error instanceof DatabasePathError)
+        return error.code;
+    if (error instanceof LocalityError)
+        return error.code;
+    if (typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && typeof error.code === 'string'
+        && error.code.startsWith('PROTOCOL_'))
+        return error.code;
+    return 'INTERNAL';
+};
+const SQLITE_EXPERIMENTAL_WARNING = 'SQLite is an experimental feature and might change at any time';
+// @@@node-sqlite-warning - Node 22 emits this during import; suppress only that exact warning so the
+// CLI's stderr remains its frozen single line while every unrelated warning keeps its normal path.
+const loadOpenProtocol = async () => {
+    const originalEmitWarning = process.emitWarning;
+    process.emitWarning = ((warning, ...args) => {
+        const message = warning instanceof Error ? warning.message : warning;
+        if (message === SQLITE_EXPERIMENTAL_WARNING)
+            return;
+        Reflect.apply(originalEmitWarning, process, [warning, ...args]);
+    });
+    try {
+        return (await import('@spexcode/session-protocol')).openProtocol;
+    }
+    finally {
+        process.emitWarning = originalEmitWarning;
+    }
+};
+export async function runCli(options = {}) {
+    const stdout = options.stdout ?? (text => process.stdout.write(text));
+    const stderr = options.stderr ?? (text => process.stderr.write(text));
+    let protocol;
+    try {
+        const parsed = parseCommand(options.argv ?? process.argv.slice(2));
+        const databasePath = resolveDatabasePath({
+            databasePath: parsed.values.get('database-path'),
+            env: options.env,
+        });
+        const dependencies = options.dependencies ?? {
+            open: await loadOpenProtocol(),
+            requireLocal: requireLocalDatabasePath,
+        };
+        dependencies.requireLocal(databasePath, { assumeLocal: parsed.assumeLocal });
+        protocol = dependencies.open(databasePath);
+        const sessionId = parsed.values.get('session-id');
+        let result;
+        if (parsed.command === 'initialize') {
+            result = protocol.initialize(sessionId);
+        }
+        else if (parsed.command === 'enqueue') {
+            const headers = Object.fromEntries(parsed.headers);
+            result = renderMessage(protocol.enqueue(sessionId, {
+                kind: parsed.values.get('kind'),
+                body: Buffer.from(parsed.values.get('body'), 'utf8'),
+                ...(parsed.values.has('sender-session-id')
+                    ? { senderSessionId: parsed.values.get('sender-session-id') }
+                    : {}),
+                ...(parsed.values.has('idempotency-key')
+                    ? { idempotencyKey: parsed.values.get('idempotency-key') }
+                    : {}),
+                ...(parsed.headers.length > 0 ? { headers } : {}),
+            }));
+        }
+        else if (parsed.command === 'dequeue') {
+            const message = protocol.dequeue(sessionId);
+            result = message === null ? null : renderMessage(message);
+        }
+        else {
+            result = protocol.listPending(sessionId).map(renderMessage);
+        }
+        stdout(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const code = errorCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        const repair = code === 'PROTOCOL_PATH_PARENT_MISSING'
+            ? '; create the parent directory or choose --database-path with an existing parent'
+            : '';
+        stderr(`spex-session: ${code}: ${message}${repair}\n`);
+        return code === 'USAGE' ? 2 : 1;
+    }
+    finally {
+        protocol?.close();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export { LocalityError, requireLocalDatabasePath } from './locality.js';
+export type { LocalityRefusalCode } from './locality.js';
+export { resolveDatabasePath } from './path.js';
+export type { ResolveDatabasePathOptions, SelfLaunchEnvironment } from './path.js';
+import type { ProtocolTransaction } from '@spexcode/session-protocol';
+import { type BindingOptions, type RuntimeBinding } from '@spexcode/session-runtime';
+/**
+ * Native identity supplied by the harness adapter that owns this self-launch.
+ * The CLI session id is deliberately not accepted as a native identity.
+ */
+export interface SelfLaunchRuntimeIdentity {
+    nativeSessionId: string;
+    nativeStartToken: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SelfLaunchProtocol {
+    withTransaction<T>(body: (tx: ProtocolTransaction) => T): T;
+}
+export interface SelfLaunchBindingOptions extends BindingOptions {
+    runtimeKind?: string;
+}
+/**
+ * Attach a caller-owned native harness identity to an existing protocol address.
+ * This is the only self-launch/runtime seam; it does not launch, probe, or stop a harness.
+ */
+export declare function bindSelfLaunchRuntime(protocol: SelfLaunchProtocol, protocolSessionId: string, identity: SelfLaunchRuntimeIdentity, options?: SelfLaunchBindingOptions): RuntimeBinding;
+export declare function resolveSelfLaunchRuntime(protocol: SelfLaunchProtocol, protocolSessionId: string): RuntimeBinding | null;
+export declare function unbindSelfLaunchRuntime(protocol: SelfLaunchProtocol, protocolSessionId: string, options?: BindingOptions): RuntimeBinding;

package/dist/index.js

@@ -0,0 +1,25 @@
+export { LocalityError, requireLocalDatabasePath } from './locality.js';
+export { resolveDatabasePath } from './path.js';
+import { openRuntimeBindings, } from '@spexcode/session-runtime';
+const SELF_LAUNCH_NAMESPACE = 'self-launch';
+/**
+ * Attach a caller-owned native harness identity to an existing protocol address.
+ * This is the only self-launch/runtime seam; it does not launch, probe, or stop a harness.
+ */
+export function bindSelfLaunchRuntime(protocol, protocolSessionId, identity, options = {}) {
+    const bindings = openRuntimeBindings(protocol);
+    return protocol.withTransaction(tx => bindings.bind(tx, protocolSessionId, {
+        namespace: SELF_LAUNCH_NAMESPACE,
+        runtimeKind: options.runtimeKind ?? 'self-launch',
+        nativeSessionId: identity.nativeSessionId,
+        nativeStartToken: identity.nativeStartToken,
+        metadata: identity.metadata,
+    }, options));
+}
+export function resolveSelfLaunchRuntime(protocol, protocolSessionId) {
+    return openRuntimeBindings(protocol).resolve(SELF_LAUNCH_NAMESPACE, protocolSessionId);
+}
+export function unbindSelfLaunchRuntime(protocol, protocolSessionId, options = {}) {
+    const bindings = openRuntimeBindings(protocol);
+    return protocol.withTransaction(tx => bindings.unbind(tx, SELF_LAUNCH_NAMESPACE, protocolSessionId, options));
+}

package/dist/locality.d.ts

@@ -0,0 +1,20 @@
+export type LocalityRefusalCode = 'LOCALITY_NETWORK_FILESYSTEM' | 'LOCALITY_UNDETERMINED' | 'LOCALITY_DETECTOR_UNAVAILABLE' | 'LOCALITY_PROBE_FAILED';
+export declare class LocalityError extends Error {
+    readonly code: LocalityRefusalCode;
+    constructor(code: LocalityRefusalCode, message: string, cause?: unknown);
+}
+export interface FilesystemClassification {
+    readonly locality: 'local' | 'network' | 'undetermined';
+    readonly name: string;
+}
+export declare function classifyFilesystemType(type: number | bigint): FilesystemClassification;
+export interface LocalityDetector {
+    readonly platform: string;
+    statfsType(parentPath: string): number | bigint;
+}
+export declare function requireLocalDatabasePathWithDetector(databasePath: string, options: {
+    assumeLocal?: boolean;
+}, detector: LocalityDetector): string;
+export declare function requireLocalDatabasePath(databasePath: string, options?: {
+    assumeLocal?: boolean;
+}): string;

package/dist/locality.js

@@ -0,0 +1,83 @@
+import { statfsSync } from 'node:fs';
+import { isAbsolute, dirname } from 'node:path';
+import { DatabasePathError } from './path.js';
+export class LocalityError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'LocalityError';
+        this.code = code;
+    }
+}
+// @@@network-magic-evidence - These header values drive classifier vectors, not real-mount evidence;
+// this host has no corresponding network mount on which to run them.
+const NETWORK_FILESYSTEM_TYPES = [
+    { name: 'NFS', type: 0x6969 },
+    { name: 'SMB', type: 0x517b },
+    { name: 'CIFS', type: 0xff534d42 },
+    { name: 'SMB2', type: 0xfe534d42 },
+    { name: '9P', type: 0x01021997 },
+    { name: 'CEPH', type: 0x00c36400 },
+    { name: 'AFS', type: 0x5346414f },
+    { name: 'AFS_FS', type: 0x6b414653 },
+    { name: 'CODA', type: 0x73757245 },
+    { name: 'OCFS2', type: 0x7461636f },
+    { name: 'NCP', type: 0x564c },
+];
+const LOCAL_FILESYSTEM_TYPES = [
+    { name: 'EXT2/3/4', type: 0xef53 },
+    { name: 'BTRFS', type: 0x9123683e },
+    { name: 'XFS', type: 0x58465342 },
+    { name: 'F2FS', type: 0xf2f52010 },
+    { name: 'TMPFS', type: 0x01021994 },
+    { name: 'OVERLAYFS', type: 0x794c7630 },
+    { name: 'ZFS', type: 0x2fc12fc1 },
+];
+const unsignedMagic = (type) => Number(BigInt.asUintN(32, BigInt(type)));
+export function classifyFilesystemType(type) {
+    const magic = unsignedMagic(type);
+    const network = NETWORK_FILESYSTEM_TYPES.find(candidate => candidate.type === magic);
+    if (network)
+        return { locality: 'network', name: network.name };
+    const local = LOCAL_FILESYSTEM_TYPES.find(candidate => candidate.type === magic);
+    if (local)
+        return { locality: 'local', name: local.name };
+    return { locality: 'undetermined', name: `0x${magic.toString(16)}` };
+}
+export function requireLocalDatabasePathWithDetector(databasePath, options, detector) {
+    if (!isAbsolute(databasePath)) {
+        throw new DatabasePathError('PROTOCOL_PATH_NOT_ABSOLUTE', 'databasePath must be absolute before locality detection');
+    }
+    if (options.assumeLocal)
+        return databasePath;
+    const parent = dirname(databasePath);
+    if (detector.platform !== 'linux') {
+        throw new LocalityError('LOCALITY_DETECTOR_UNAVAILABLE', `no filesystem locality detector for platform ${detector.platform}; pass --assume-local-storage only after auditing ${parent}`);
+    }
+    let type;
+    try {
+        type = detector.statfsType(parent);
+    }
+    catch (error) {
+        // @@@missing-parent - Preserve the actionable path error without pretending locality was established.
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            throw new DatabasePathError('PROTOCOL_PATH_PARENT_MISSING', `database parent directory does not exist: ${parent}`, error);
+        }
+        throw new LocalityError('LOCALITY_PROBE_FAILED', `could not determine the filesystem of ${parent}`, error);
+    }
+    const classification = classifyFilesystemType(type);
+    if (classification.locality === 'network') {
+        throw new LocalityError('LOCALITY_NETWORK_FILESYSTEM', `${parent} is ${classification.name}; advisory locking is not admitted there`);
+    }
+    if (classification.locality === 'undetermined') {
+        throw new LocalityError('LOCALITY_UNDETERMINED', `filesystem type ${classification.name} at ${parent} is not on the audited local allow-list`);
+    }
+    return databasePath;
+}
+const linuxDetector = {
+    platform: process.platform,
+    statfsType: parentPath => statfsSync(parentPath).type,
+};
+export function requireLocalDatabasePath(databasePath, options = {}) {
+    return requireLocalDatabasePathWithDetector(databasePath, options, linuxDetector);
+}

package/dist/path.d.ts

@@ -0,0 +1,13 @@
+type DatabasePathErrorCode = 'PROTOCOL_PATH_NOT_ABSOLUTE' | 'PROTOCOL_PATH_INVALID' | 'PROTOCOL_PATH_PARENT_MISSING';
+export declare class DatabasePathError extends Error {
+    readonly code: DatabasePathErrorCode;
+    constructor(code: DatabasePathErrorCode, message: string, cause?: unknown);
+}
+export type SelfLaunchEnvironment = Readonly<Record<string, string | undefined>>;
+export interface ResolveDatabasePathOptions {
+    databasePath?: string;
+    env?: SelfLaunchEnvironment;
+    readFile?: (path: string) => string;
+}
+export declare function resolveDatabasePath(options?: ResolveDatabasePathOptions): string;
+export {};

package/dist/path.js

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+export class DatabasePathError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'DatabasePathError';
+        this.code = code;
+    }
+}
+export function resolveDatabasePath(options = {}) {
+    const env = options.env ?? process.env;
+    let databasePath = options.databasePath ?? env.SPEX_SESSION_DATABASE_PATH;
+    if (databasePath === undefined && env.SPEX_SESSION_CONFIG) {
+        const configPath = env.SPEX_SESSION_CONFIG;
+        let config;
+        try {
+            config = JSON.parse((options.readFile ?? ((path) => readFileSync(path, 'utf8')))(configPath));
+        }
+        catch (error) {
+            throw new DatabasePathError('PROTOCOL_PATH_INVALID', `could not read session config ${configPath}`, error);
+        }
+        if (typeof config !== 'object'
+            || config === null
+            || typeof config.databasePath !== 'string'
+            || !config.databasePath) {
+            throw new DatabasePathError('PROTOCOL_PATH_INVALID', `session config ${configPath} must contain databasePath`);
+        }
+        databasePath = config.databasePath;
+    }
+    if (databasePath === undefined) {
+        const home = env.SPEXCODE_HOME || (env.HOME ? join(env.HOME, '.spexcode') : undefined);
+        if (!home) {
+            throw new DatabasePathError('PROTOCOL_PATH_INVALID', 'HOME or SPEXCODE_HOME is required for the default database path');
+        }
+        databasePath = join(home, 'sessions.sqlite');
+    }
+    if (databasePath.length === 0) {
+        throw new DatabasePathError('PROTOCOL_PATH_INVALID', 'databasePath must not be empty');
+    }
+    if (!isAbsolute(databasePath)) {
+        throw new DatabasePathError('PROTOCOL_PATH_NOT_ABSOLUTE', 'databasePath must be absolute and is never resolved from cwd');
+    }
+    return databasePath;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@spexcode/session-selflaunch",
+  "version": "0.6.8",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "A fail-closed self-launch adopter for the SpexCode session protocol.",
+  "bin": {
+    "spex-session": "./bin/spex-session.mjs"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/session-protocol": "0.6.8",
+    "@spexcode/session-runtime": "0.6.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}