import { namelib, ndm_proxy, ndn } from 'buckyos/node' import type { CommandDefinition, CommandModule, JsonSchema } from '../core/command.ts' import type { CommandContext } from '../core/context.ts' import { EXIT_AUTH, EXIT_INTERNAL, EXIT_OPERATION, EXIT_PERMISSION, EXIT_TIMEOUT, EXIT_UNAVAILABLE, ToolError, UsageError, } from '../core/errors.ts' import { type TaskObservation, waitForTask } from '../core/task.ts' import { getHost, type HostFile, type HostFileInfo, isHostError } from '../runtime/host.ts' const isAbsolute = (path: string) => getHost().path.isAbsolute(path) const resolve = (...parts: string[]) => getHost().path.resolve(...parts) const CONTROL_PANEL_SERVICE = 'control-panel' const PLAN_SCHEMA_VERSION = 4 const STAGING_RELEASE_TIMEOUT_MS = 5_000 const ZIP_LOCAL_MAGIC = [0x50, 0x4b, 0x03, 0x04] as const const OBJECT_OUTPUT: JsonSchema = { type: 'object', additionalProperties: true } const INSTALL_POLICIES = [ 'strict-public', 'normal', 'trusted-share', 'local-developer', 'system-internal', ] as const type PikgPurpose = 'inspect' | 'install' type SourceKind = 'catalog' | 'pikg' | 'url' export interface PikgSnapshot { kind: 'pikg' | 'url' display: string path: string localFileId?: string digest: string size: number } export interface PikgStagingMetadata { schema_version: number handle: string pikg_digest: string size: number purpose: PikgPurpose expires_at?: number } export interface AppModuleDependencies { download?: (url: URL, signal: AbortSignal) => Promise stagePikg?: ( ctx: CommandContext, snapshot: PikgSnapshot, purpose: PikgPurpose, ) => Promise sleep?: (milliseconds: number, signal: AbortSignal) => Promise } interface CatalogSource { kind: 'catalog' display: string serviceSource: { kind: 'identifier'; identifier: string } } interface StagedSource { kind: 'pikg' | 'url' display: string snapshot: PikgSnapshot staging: PikgStagingMetadata serviceSource: { kind: 'local_pikg'; staging_handle: string } } type PreparedSource = CatalogSource | StagedSource interface InstallInspection { schema_version: number plan: Record resolution_status: Record status: Record } export function createAppModule(dependencies: AppModuleDependencies = {}): CommandModule { const commands = [ fetchCommand(dependencies), listCommand(), getCommand(), installCommand(dependencies), upgradeCommand(dependencies), uninstallCommand(dependencies), cancelCommand(), lifecycleCommand('start', 'Start an installed App'), lifecycleCommand('stop', 'Stop an installed App'), restartCommand(), statusCommand(), publishCommand(), ] return { name: 'app', summary: 'Inspect, install, upgrade, and control Apps', commands: commands.map((command) => { const handler = command.handler return { ...command, handler: async (ctx, input) => sanitizeAppOutput(await handler(ctx, input)), } }), } } function cancelCommand(): CommandDefinition { return { verb: 'cancel', summary: 'Cancel an installation or upgrade task and release its App mutation', positionals: [{ name: 'task_id', description: 'Installation Task ID', required: true }], options: [{ name: 'force', description: 'Defer staging cleanup after cancellation', type: 'boolean', }], inputSchema: { type: 'object', properties: { task_id: { type: 'string', minLength: 1 }, force: { type: 'boolean' } }, required: ['task_id'], additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'sync', requiresSession: true, examples: ['buckyos app cancel t-0123456789abcdef0123456789abcdef --force'], handler: async (ctx, input) => await callControl(ctx, 'apps.install.cancel', { task_id: expectString(input, 'task_id'), force: input.force === true, }), } } function fetchCommand(dependencies: AppModuleDependencies): CommandDefinition { return { verb: 'fetch', summary: 'Inspect an App source and optionally write a fresh-install plan', positionals: [ { name: 'source', description: 'Catalog name/DID, local PIKG path, or HTTP(S) URL', required: false, }, ], options: sourceOptions([ { name: 'plan', description: 'Write the v4 InstallPlan to this JSON file', type: 'string' }, ownerOption(), policyOption(), ]), inputSchema: sourceInputSchema({ plan: { type: 'string', minLength: 1 }, owner_user_id: { type: 'string', minLength: 1 }, policy: { type: 'string', enum: [...INSTALL_POLICIES] }, target: { type: 'object', additionalProperties: true }, install_params: { type: 'object', additionalProperties: true }, }), outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'read' }, asyncMode: 'sync', requiresSession: true, examples: [ 'buckyos app fetch did:bns:app1.alice', 'buckyos app fetch ./demo-0.1.0.pikg --plan ./demo.install-plan.json', ], handler: async (ctx, input) => await fetchApp(ctx, input, dependencies), } } function listCommand(): CommandDefinition { return { verb: 'list', summary: 'List visible installed Apps', inputSchema: emptyInputSchema(), outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'read' }, asyncMode: 'sync', requiresSession: true, examples: ['buckyos app list'], handler: async (ctx) => await callControl(ctx, 'apps.list', {}), } } function getCommand(): CommandDefinition { return selectorCommand({ verb: 'get', summary: 'Get installation and runtime details for one App', access: 'read', asyncMode: 'sync', handler: async (ctx, input) => { const selector = normalizeAppSelector(expectString(input, 'app_name')) const [details, status] = await Promise.all([ callControl(ctx, 'apps.details', { selector }), callControl(ctx, 'apps.status', { selector }), ]) return { details, status } }, }) } function installCommand(dependencies: AppModuleDependencies): CommandDefinition { return { verb: 'install', summary: 'Install from a v4 plan or upgrade an existing App from a source', positionals: [ { name: 'source', description: 'Catalog name/DID, local PIKG path, or HTTP(S) URL', required: false, }, ], options: sourceOptions([ { name: 'plan', description: 'Fresh-install v4 InstallPlan JSON file', type: 'string' }, { name: 'dry-run', property: 'dry_run', description: 'Preflight and print without submitting', type: 'boolean', }, { name: 'no-wait', property: 'no_wait', description: 'Return immediately after task creation', type: 'boolean', }, policyOption(), ]), inputSchema: sourceInputSchema({ plan: { type: 'string', minLength: 1 }, dry_run: { type: 'boolean' }, no_wait: { type: 'boolean' }, policy: { type: 'string', enum: [...INSTALL_POLICIES] }, }), outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'either', requiresSession: true, examples: [ 'buckyos app install did:bns:app1.alice --plan ./app1.install-plan.json', 'buckyos --yes app install https://example.com/app1-1.2.0.pikg', ], handler: async (ctx, input) => await installApp(ctx, input, dependencies), } } function upgradeCommand(dependencies: AppModuleDependencies): CommandDefinition { return { verb: 'upgrade', summary: 'Check and apply Catalog upgrades', positionals: [ { name: 'app_name', description: 'Installed App name or DID; omit for all', required: false }, ], options: [ { name: 'dry-run', property: 'dry_run', description: 'Only show the upgrade preflight', type: 'boolean', }, { name: 'no-wait', property: 'no_wait', description: 'Return immediately after task creation', type: 'boolean', }, policyOption(), ], inputSchema: { type: 'object', properties: { app_name: { type: 'string', minLength: 1 }, dry_run: { type: 'boolean' }, no_wait: { type: 'boolean' }, policy: { type: 'string', enum: [...INSTALL_POLICIES] }, }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'either', requiresSession: true, examples: ['buckyos app upgrade', 'buckyos --yes app upgrade did:bns:app1.alice'], handler: async (ctx, input) => await upgradeApps(ctx, input, dependencies), } } function uninstallCommand(dependencies: AppModuleDependencies): CommandDefinition { return { ...selectorCommand({ verb: 'uninstall', summary: 'Uninstall an App and explicitly retain or delete its managed data', access: 'destructive', asyncMode: 'task', handler: async (ctx, input) => await uninstallApp(ctx, input, dependencies), }), options: [ { name: 'data', description: 'Managed data disposition', type: 'string', required: true, enum: ['retain', 'delete'], }, { name: 'dry-run', property: 'dry_run', description: 'Only show the uninstall preflight', type: 'boolean', }, { name: 'no-wait', property: 'no_wait', description: 'Return immediately after task creation', type: 'boolean', }, ], inputSchema: { type: 'object', properties: { app_name: { type: 'string', minLength: 1 }, data: { type: 'string', enum: ['retain', 'delete'] }, dry_run: { type: 'boolean' }, no_wait: { type: 'boolean' }, }, required: ['app_name', 'data'], additionalProperties: false, }, examples: ['buckyos app uninstall app1 --data retain'], } } function lifecycleCommand(verb: 'start' | 'stop', summary: string): CommandDefinition { return { ...selectorCommand({ verb, summary, access: 'write', asyncMode: verb === 'start' ? 'task' : 'either', handler: async (ctx, input) => await mutateLifecycle(ctx, input, verb), }), options: [ { name: 'no-wait', property: 'no_wait', description: 'Return immediately after task creation', type: 'boolean', }, ], inputSchema: { type: 'object', properties: { app_name: { type: 'string', minLength: 1 }, no_wait: { type: 'boolean' }, }, required: ['app_name'], additionalProperties: false, }, } } function restartCommand(): CommandDefinition { return { ...selectorCommand({ verb: 'restart', summary: 'Recreate the runtime instances for an installed App', access: 'write', asyncMode: 'task', handler: async (ctx, input) => await mutateLifecycle(ctx, input, 'restart'), }), options: [ { name: 'strategy', description: 'Restart strategy; rolling is currently unsupported', type: 'string', enum: ['recreate', 'rolling'], }, { name: 'no-wait', property: 'no_wait', description: 'Return immediately after task creation', type: 'boolean', }, ], inputSchema: { type: 'object', properties: { app_name: { type: 'string', minLength: 1 }, strategy: { type: 'string', enum: ['recreate', 'rolling'] }, no_wait: { type: 'boolean' }, }, required: ['app_name'], additionalProperties: false, }, examples: ['buckyos app restart app1'], } } function statusCommand(): CommandDefinition { return { verb: 'status', summary: 'Show desired, task, scheduled, runtime, version, and readiness state', positionals: [ { name: 'app_name', description: 'Installed App name or DID; omit for all', required: false }, ], inputSchema: { type: 'object', properties: { app_name: { type: 'string', minLength: 1 } }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'read' }, asyncMode: 'sync', requiresSession: true, examples: ['buckyos app status', 'buckyos app status did:bns:app1.alice'], handler: async (ctx, input) => { if (typeof input.app_name === 'string') { const selector = normalizeAppSelector(input.app_name) const [status, details] = await Promise.all([ callControl(ctx, 'apps.status', { selector }), callControl(ctx, 'apps.details', { selector }), ]) const detailObject = expectObject(details, 'apps.details response') const summary = expectObject(detailObject.summary, 'apps.details summary') return { ...expectObject(status, 'apps.status response'), web_hosts: Array.isArray(summary.web_hosts) ? summary.web_hosts : [], } } const listed = expectObject(await callControl(ctx, 'apps.list', {}), 'apps.list response') const apps = Array.isArray(listed.apps) ? listed.apps : [] const items = await Promise.all(apps.map(async (item) => { const app = expectObject(item, 'apps.list item') const selector = expectString(app, 'app_instance_id') return { ...expectObject( await callControl(ctx, 'apps.status', { selector }), 'apps.status response', ), web_hosts: Array.isArray(app.web_hosts) ? app.web_hosts : [], } })) return { total: items.length, items } }, } } function publishCommand(): CommandDefinition { return { verb: 'publish', summary: 'Package a directory on the control-panel node into the Zone Repo as an App candidate', description: 'Calls control-panel app.publish: packages (a path on the control-panel node; nothing is uploaded) with the AppDoc template, stores PackageMeta and the AppDoc in the Zone Repo/NamedStore, and stages a self-checked PIKG there. The AppDoc is not Owner-signed and no BNS/App DID record is updated, so this is not an authoritative App release.', positionals: [ { name: 'local_dir', description: 'Absolute source directory on the control-panel node' }, ], options: [ { name: 'app-doc', property: 'app_doc', description: 'AppDoc template JSON file (pkg_list entries without pkg_objid)', type: 'string', required: true, }, { name: 'app-type', property: 'app_type', description: 'App type; defaults to the template app_type', type: 'string', enum: ['dapp', 'web', 'agent', 'ext_tools'], }, ], inputSchema: { type: 'object', properties: { local_dir: { type: 'string', minLength: 1 }, app_doc: { type: 'string', minLength: 1 }, app_type: { type: 'string', enum: ['dapp', 'web', 'agent', 'ext_tools'] }, }, required: ['local_dir', 'app_doc'], additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'sync', requiresSession: true, examples: [ 'buckyos app publish /srv/build/demo-web --app-doc ./demo-web.appdoc.json', 'buckyos app publish /srv/build/demo-agent --app-doc ./demo-agent.appdoc.json --app-type agent', 'buckyos app publish /srv/build/ext-media --app-doc ./dapp_dist/APPDOC.json', ], handler: async (ctx, input) => { const localDir = expectString(input, 'local_dir') if (!isAbsolute(localDir)) { throw new UsageError( 'INVALID_ARGUMENT', 'local_dir must be an absolute path on the control-panel node', ) } let appDoc: unknown try { appDoc = JSON.parse( await getHost().readTextFile(resolveFromCwd(ctx, expectString(input, 'app_doc'))), ) } catch (error) { throw new UsageError( 'INVALID_APP_DOC', `failed to read AppDoc template: ${errorMessage(error)}`, ) } if (!isObject(appDoc)) { throw new UsageError('INVALID_APP_DOC', 'AppDoc template must be a JSON object') } const result = expectObject( await callControl(ctx, 'app.publish', { local_dir: localDir, app_doc: appDoc, ...(typeof input.app_type === 'string' ? { app_type: input.app_type } : {}), }), 'app.publish response', ) const { ok: _ok, ...published } = result return { ...published, publish_status: expectString(result, 'publish_status'), app_doc_signature: 'not-signed', app_did_publication: 'not-published', } }, } } async function fetchApp( ctx: CommandContext, input: Record, dependencies: AppModuleDependencies, ): Promise> { const source = await prepareSource(ctx, input, 'inspect', dependencies) try { let inspection = await inspectSource(ctx, source, input) const planPathInput = optionalString(input.plan) let planPath: string | undefined if (planPathInput) { inspection = await finalizePlanChoices(ctx, source, input, inspection) const plan = inspection.plan assertPortablePlan(plan) planPath = resolveFromCwd(ctx, planPathInput) await writePlanFile(ctx, planPath, plan) } return { source: sourceSummary(source), app: inspection.plan.app, source_identity: inspection.plan.source_identity, resolution: inspection.resolution_status, status: inspection.status, plan_path: planPath ?? null, plan_fingerprint: planPath ? inspection.plan.plan_fingerprint : null, } } finally { await releaseStaging(ctx, source) } } async function installApp( ctx: CommandContext, input: Record, dependencies: AppModuleDependencies, ): Promise> { rejectDryRunNoWait(input) const submittedPlan = optionalString(input.plan) ? await readPlanFile(resolveFromCwd(ctx, String(input.plan))) : undefined const source = await prepareSource(ctx, input, 'install', dependencies) let keepStaging = false try { let inspection = submittedPlan ? await recomputePlan(ctx, source, input, submittedPlan) : await inspectSource(ctx, source, input) verifyPikgBinding(source, submittedPlan ?? inspection.plan) if ((inspection.plan.app_doc as Record | undefined)?.app_type === 'ext_tools') { throw new ToolError( 'EXT_TOOLS_NOT_AN_APP', 'an extension tool package is not installed as an App: publish it to the Repo with `buckyos app publish`, then enable it for the Zone on the management page', ) } const app = expectObject(inspection.plan.app, 'inspection.plan.app') const appDid = expectString(app, 'did') const plannedOwner = submittedPlan ? expectString(submittedPlan, 'owner_user_id') : undefined const installed = await findInstalled(ctx, appDid, plannedOwner) if (submittedPlan && installed) { throw new ToolError( 'PLAN_NOT_APPLICABLE', 'a fresh-install plan cannot be applied over an installed App', ) } if (!submittedPlan && !installed) { throw new ToolError( 'PLAN_REQUIRED', `App is not installed; run app fetch ${source.display} --plan first`, ) } if (submittedPlan) { assertPlanMatchesInspection(submittedPlan, inspection) } else { const scope = installedScope(installed!) inspection = await inspectSource(ctx, source, input, { ...scope, action: 'upgrade' }) verifyPikgBinding(source, inspection.plan) } if (input.dry_run === true) { return { action: 'dry_run', source: sourceSummary(source), plan: inspection.plan, status: inspection.status, } } if (planUse(inspection.plan) === 'SATISFIED') { return satisfiedResult(inspection) } await confirmChange(ctx, 'install', confirmationSummary(inspection)) const params = { ...sourceRpcParams(source), ...planScopeAndOptions(inspection.plan), options: installOptions(input), plan: submittedPlan ?? inspection.plan, approved_plan_fingerprint: expectString(inspection.plan, 'plan_fingerprint'), idempotency_key: idempotencyKey(ctx), } const submitted = expectObject( await callControl(ctx, 'apps.submit', params), 'apps.submit response', ) if (submitted.action === 'satisfied' || submitted.task_id === null) { return submitted } const taskId = expectString(submitted, 'task_id') keepStaging = true if (input.no_wait === true) return submitted try { const status = await waitForTask(ctx, taskId, { observe: observeInstallTask, sleep: dependencies.sleep, }) return { ...submitted, status } } finally { keepStaging = false } } finally { if (!keepStaging) await releaseStaging(ctx, source) } } async function upgradeApps( ctx: CommandContext, input: Record, dependencies: AppModuleDependencies, ): Promise> { rejectDryRunNoWait(input) const selector = typeof input.app_name === 'string' ? normalizeAppSelector(input.app_name) : undefined const check = expectObject( await callControl(ctx, 'apps.upgrade.check', selector ? { selector } : {}), 'apps.upgrade.check response', ) const items = Array.isArray(check.items) ? check.items : [] const actionable = items.filter((value) => { const item = isObject(value) ? value : {} return item.state === 'UPDATE_AVAILABLE' || item.state === 'PERMISSION_RECONFIRM_REQUIRED' }) if (input.dry_run === true) return { action: 'dry_run', check } if (actionable.length === 0) return { action: 'satisfied', total: items.length, items } await confirmChange(ctx, 'upgrade', { total: items.length, update_count: actionable.length, items, }) let submitted: Record let installTask = false if (selector) { const item = expectObject(actionable[0], 'upgrade item') const appDid = expectString(item, 'app_did') const details = await findInstalled(ctx, appDid) if (!details) throw new ToolError('RESOURCE_NOT_FOUND', `App is not installed: ${appDid}`) const source: CatalogSource = { kind: 'catalog', display: appDid, serviceSource: { kind: 'identifier', identifier: appDid }, } const inspection = await inspectSource(ctx, source, input, { ...installedScope(details), action: 'upgrade', }) submitted = expectObject( await callControl(ctx, 'apps.submit', { ...sourceRpcParams(source), ...planScopeAndOptions(inspection.plan), options: installOptions(input), plan: inspection.plan, approved_plan_fingerprint: expectString(inspection.plan, 'plan_fingerprint'), idempotency_key: idempotencyKey(ctx), }), 'apps.submit response', ) installTask = submitted.task_id !== null } else { submitted = expectObject( await callControl(ctx, 'apps.upgrade', { idempotency_key: idempotencyKey(ctx) }), 'apps.upgrade response', ) } if (submitted.task_id === null || submitted.action === 'satisfied') return submitted const taskId = expectString(submitted, 'task_id') if (input.no_wait === true) return submitted const status = await waitForTask(ctx, taskId, { observe: installTask ? observeInstallTask : undefined, sleep: dependencies.sleep, }) return { ...submitted, status } } async function uninstallApp( ctx: CommandContext, input: Record, dependencies: AppModuleDependencies, ): Promise> { rejectDryRunNoWait(input) const selector = normalizeAppSelector(expectString(input, 'app_name')) const status = await callControl(ctx, 'apps.status', { selector }) const preflight = { action: 'uninstall', data_disposition: input.data, status } if (input.dry_run === true) return { action: 'dry_run', preflight } await confirmChange(ctx, 'uninstall', preflight) const submitted = expectObject( await callControl(ctx, 'apps.uninstall', { selector, data_disposition: input.data, idempotency_key: idempotencyKey(ctx), }), 'apps.uninstall response', ) const taskId = expectString(submitted, 'task_id') if (input.no_wait === true) return submitted const task = await waitForTask(ctx, taskId, { sleep: dependencies.sleep }) return { ...submitted, status: task } } async function mutateLifecycle( ctx: CommandContext, input: Record, verb: 'start' | 'stop' | 'restart', ): Promise> { if (input.strategy === 'rolling') { throw new ToolError( 'UNSUPPORTED_STRATEGY', 'rolling restart is not supported by the current deployment strategy', ) } const selector = normalizeAppSelector(expectString(input, 'app_name')) const submitted = expectObject( await callControl(ctx, `apps.${verb}`, { selector, idempotency_key: idempotencyKey(ctx), ...(verb === 'restart' ? { restart_strategy: input.strategy ?? 'recreate' } : {}), }), `apps.${verb} response`, ) const taskId = expectString(submitted, 'task_id') if (input.no_wait === true) return submitted const task = await waitForTask(ctx, taskId) return { ...submitted, status: task } } /** A local `.pikg` staged for an inspection or import that is not an App install. */ export async function stageLocalPikg(ctx: CommandContext, path: string): Promise { const prepared = await prepareSource(ctx, { pikg: path }, 'inspect', {}) if (prepared.kind === 'catalog') throw new UsageError('INVALID_PIKG_SOURCE', 'not a local PIKG') return prepared.staging } async function prepareSource( ctx: CommandContext, input: Record, purpose: PikgPurpose, dependencies: AppModuleDependencies, ): Promise { const classified = await classifySource(ctx, input) if (classified.kind === 'catalog') return classified const host = getHost() const localDirectory = localPikgDirectory(ctx) let directory: string let localFileId: string | undefined if (localDirectory) { try { await host.mkdir(localDirectory, { recursive: true, mode: 0o700 }) directory = localDirectory localFileId = crypto.randomUUID().replaceAll('-', '') } catch (error) { if (!isHostError(error, 'PermissionDenied') && !isHostError(error, 'NotFound')) throw error } } if (!localFileId) { await host.mkdir(ctx.configStore.root, { recursive: true, mode: 0o700 }) directory = await host.makeTempDir({ dir: ctx.configStore.root, prefix: '.pikg-' }) } let path = host.path.join(directory!, `${localFileId ?? 'source'}.pikg`) const snapshotAt = (destination: string) => classified.kind === 'url' ? downloadPikg(classified.url, destination, dependencies.download, ctx.signal) : readPikg(classified.path, destination, ctx.signal) try { let snapshot: PikgSnapshot try { snapshot = await snapshotAt(path) } catch (error) { if (!localFileId || !isHostError(error, 'PermissionDenied')) throw error await host.remove(path).catch(() => {}) localFileId = undefined await host.mkdir(ctx.configStore.root, { recursive: true, mode: 0o700 }) directory = await host.makeTempDir({ dir: ctx.configStore.root, prefix: '.pikg-' }) path = host.path.join(directory, 'source.pikg') snapshot = await snapshotAt(path) } snapshot.localFileId = localFileId const stage = dependencies.stagePikg ?? stagePikg const metadata = await stage(ctx, snapshot, purpose) if (metadata.schema_version !== PLAN_SCHEMA_VERSION) { throw new ToolError('UNSUPPORTED_SCHEMA_VERSION', 'staging returned a non-v4 schema') } if (metadata.pikg_digest !== snapshot.digest || metadata.size !== snapshot.size) { throw new ToolError( 'PIKG_DIGEST_MISMATCH', 'the staged PIKG does not match the client byte snapshot', EXIT_OPERATION, false, { expected_digest: snapshot.digest, staged_digest: metadata.pikg_digest, expected_size: snapshot.size, staged_size: metadata.size, }, ) } if (metadata.purpose !== purpose) { throw new ToolError( 'INVALID_SERVICE_RESPONSE', 'staging purpose does not match the request', 9, ) } return { kind: snapshot.kind, display: snapshot.display, snapshot, staging: metadata, serviceSource: { kind: 'local_pikg', staging_handle: metadata.handle }, } } finally { await host.remove(localFileId ? path : directory!, { recursive: !localFileId }) .catch(() => {}) } } async function classifySource( ctx: CommandContext, input: Record, ): Promise< | CatalogSource | { kind: 'pikg'; path: string } | { kind: 'url'; url: URL } > { const positional = optionalString(input.source) const pikg = optionalString(input.pikg) if (positional && pikg) { throw new UsageError('ARGUMENT_CONFLICT', ' and --pikg are mutually exclusive') } const raw = pikg ?? positional if (!raw) throw new UsageError('MISSING_ARGUMENT', 'source or --pikg is required') const forced = pikg ? 'pikg' : optionalString(input.from) if (pikg && forced && forced !== 'pikg') { throw new UsageError('ARGUMENT_CONFLICT', '--pikg conflicts with --from') } if (forced === 'url') return { kind: 'url', url: parsePikgUrl(raw) } if (forced === 'pikg') return { kind: 'pikg', path: resolveFromCwd(ctx, raw) } if (forced === 'catalog') { return { kind: 'catalog', display: normalizeCatalogIdentifier(raw), serviceSource: { kind: 'identifier', identifier: normalizeCatalogIdentifier(raw) }, } } if (forced) throw new UsageError('INVALID_ARGUMENT', `invalid --from value: ${forced}`) if (/^https?:\/\//i.test(raw)) return { kind: 'url', url: parsePikgUrl(raw) } const candidatePath = resolveFromCwd(ctx, raw) const stat = await tryLstat(candidatePath) if (stat) { if (!stat.isFile) { throw new UsageError('INVALID_PIKG_SOURCE', `PIKG source is not a regular file: ${raw}`) } return { kind: 'pikg', path: candidatePath } } if (looksLikeLocalPath(raw)) { throw new UsageError('PIKG_NOT_FOUND', `PIKG source does not exist: ${raw}`) } const identifier = normalizeCatalogIdentifier(raw) return { kind: 'catalog', display: identifier, serviceSource: { kind: 'identifier', identifier }, } } function localPikgDirectory(ctx: CommandContext): string | undefined { const root = getHost().policy.buckyosRoot const hostname = new URL(ctx.connection.endpoint).hostname if (!root || !['localhost', '127.0.0.1', '[::1]'].includes(hostname)) return undefined return getHost().path.join(root, 'cache', 'control_panel', 'pikg_staging', 'incoming') } async function* fileChunks(file: HostFile, size: number): AsyncGenerator { const buffer = new Uint8Array(size) while (true) { let used = 0 while (used < buffer.length) { const read = await file.read(buffer.subarray(used)) if (read === null) break if (read === 0) throw new UsageError('PIKG_READ_FAILED', 'PIKG read made no progress') used += read } if (used === 0) break yield buffer.subarray(0, used) } } async function writePikgSnapshot( path: string, chunks: AsyncIterable | Iterable, signal: AbortSignal, ): Promise<{ path: string; digest: string; size: number }> { const output = await getHost().open(path, { write: true, createNew: true, mode: 0o600 }) const hash = getHost().createHash('sha256') const magic = new Uint8Array(ZIP_LOCAL_MAGIC.length) let size = 0 try { for await (const chunk of chunks) { signal.throwIfAborted() if (size < magic.length) magic.set(chunk.subarray(0, magic.length - size), size) hash.update(chunk) size += chunk.length if (!Number.isSafeInteger(size)) throw new UsageError('PIKG_TOO_LARGE', 'PIKG is too large') let offset = 0 while (offset < chunk.length) { const written = await output.write(chunk.subarray(offset)) if (written === 0) throw new UsageError('PIKG_WRITE_FAILED', 'PIKG write made no progress') offset += written } } validatePikgSnapshot(magic.subarray(0, Math.min(size, magic.length))) await output.sync() return { path, size, digest: hash.digestHex() } } finally { await output.close() } } async function readPikg( source: string, destination: string, signal: AbortSignal, ): Promise { let file: HostFile try { file = await getHost().open(source, { read: true }) } catch (error) { throw new UsageError('PIKG_READ_FAILED', `failed to open PIKG: ${errorMessage(error)}`) } try { const before = await file.stat() if (!before.isFile) throw new UsageError('INVALID_PIKG_SOURCE', 'PIKG source is not a file') const snapshot = await writePikgSnapshot(destination, fileChunks(file, 256 * 1024), signal) const after = await file.stat() if ( snapshot.size !== before.size || before.size !== after.size || before.mtime?.getTime() !== after.mtime?.getTime() ) { throw new UsageError('PIKG_READ_FAILED', 'PIKG changed while being read') } return { kind: 'pikg', display: source, ...snapshot } } finally { await file.close() } } async function downloadPikg( url: URL, destination: string, downloader: AppModuleDependencies['download'], signal: AbortSignal, ): Promise { let chunks: Uint8Array[] | ReadableStream | undefined try { chunks = downloader ? [await downloader(url, signal)] : await defaultDownload(url, signal) const snapshot = await writePikgSnapshot(destination, chunks, signal) return { kind: 'url', display: safeUrl(url), ...snapshot } } catch (error) { if (error instanceof ToolError || isHostError(error, 'PermissionDenied')) throw error signal.throwIfAborted() throw new ToolError( 'PIKG_DOWNLOAD_FAILED', `failed to download PIKG: ${errorMessage(error)}`, 5, true, ) } finally { if (chunks instanceof ReadableStream && !chunks.locked) await chunks.cancel().catch(() => {}) } } async function defaultDownload(url: URL, signal: AbortSignal): Promise> { const response = await fetch(url, { method: 'GET', redirect: 'follow', signal }) if (!response.ok || !response.body) { await response.body?.cancel() throw new ToolError( 'PIKG_DOWNLOAD_FAILED', `PIKG download returned HTTP ${response.status}`, 5, response.status >= 500, ) } return response.body } async function stagePikg( ctx: CommandContext, snapshot: PikgSnapshot, purpose: PikgPurpose, ): Promise { const identity = { pikg_digest: snapshot.digest, size: snapshot.size, purpose } if (snapshot.localFileId) { try { const value = expectObject( await callControl(ctx, 'apps.staging.finalize', { ...identity, local_file_id: snapshot.localFileId, }), 'apps.staging.finalize response', ) return parseStagingMetadata(value) } catch (error) { if (!errorMessage(error).includes('LOCAL_PIKG_UNAVAILABLE')) throw error } } const session = ctx.session if (!session) throw new ToolError('AUTH_REQUIRED', 'authenticated session is required', 3) const token = (await session.ensureValid()).token const proxy = ndm_proxy.createNdmProxyClient({ endpoint: gatewayOrigin(ctx.connection.endpoint), sessionToken: token, fetcher: (request: RequestInfo | URL, init?: RequestInit) => fetch(normalizeNdmRequestUrl(request), { ...init, signal: ctx.signal }), }) let fileObjectId: string try { const file = await getHost().open(snapshot.path, { read: true }) const chunks = new ndn.SimpleChunkList() const hash = getHost().createHash('sha256') try { for await (const bytes of fileChunks(file, 32 * 1024 * 1024)) { ctx.signal.throwIfAborted() hash.update(bytes) const chunk = ndn.ChunkId.fromMix256Result(bytes.length, ndn.sha256Bytes(bytes)) await proxy.putChunk(chunk.toString(), bytes) chunks.appendChunk(chunk) } } finally { await file.close() } if (chunks.total_size !== snapshot.size || hash.digestHex() !== snapshot.digest) { throw new ToolError('PIKG_DIGEST_MISMATCH', 'PIKG snapshot changed during upload') } let content = chunks.body[0].toString() if (chunks.body.length > 1) { const [id, body] = chunks.genObjId() await proxy.putObject({ obj_id: id.toString(), obj_data: body }) content = id.toString() } const fileObject = new ndn.FileObject(`${snapshot.digest}.pikg`, snapshot.size, content) const [id, body] = fileObject.genObjId() await proxy.putObject({ obj_id: id.toString(), obj_data: body }) fileObjectId = id.toString() } catch (error) { if (error instanceof ToolError) throw error ctx.signal.throwIfAborted() throw new ToolError( 'PIKG_UPLOAD_FAILED', `failed to upload PIKG: ${errorMessage(error)}`, 5, true, ) } const value = expectObject( await callControl(ctx, 'apps.staging.finalize', { ...identity, source_obj_id: fileObjectId, }), 'apps.staging.finalize response', ) return parseStagingMetadata(value) } function parseStagingMetadata(value: Record): PikgStagingMetadata { return { schema_version: expectNumber(value, 'schema_version'), handle: expectString(value, 'handle'), pikg_digest: expectString(value, 'pikg_digest'), size: expectNumber(value, 'size'), purpose: expectString(value, 'purpose') as PikgPurpose, expires_at: optionalNumber(value.expires_at), } } function normalizeNdmRequestUrl(request: RequestInfo | URL): RequestInfo | URL { if (typeof request === 'string') { return request.replaceAll('%3A', ':').replaceAll('%3a', ':') } if (request instanceof URL) { return new URL(request.toString().replaceAll('%3A', ':').replaceAll('%3a', ':')) } return request } async function inspectSource( ctx: CommandContext, source: PreparedSource, input: Record, overrides: Record = {}, ): Promise { const result = await callControl(ctx, 'apps.inspect', { ...sourceRpcParams(source), ...scopeAndChoiceParams(input), ...overrides, options: installOptions(input), }) return expectInspection(result) } async function recomputePlan( ctx: CommandContext, source: PreparedSource, input: Record, plan: Record, overrides: Record = {}, ): Promise { return expectInspection( await callControl(ctx, 'apps.plan.recompute', { ...sourceRpcParams(source), ...planScopeAndOptions(plan), ...overrides, plan, options: installOptions(input), }), ) } async function finalizePlanChoices( ctx: CommandContext, source: PreparedSource, input: Record, initial: InstallInspection, ): Promise { let inspection = initial const configReady = readinessValue(inspection, 'config') === 'READY' if (ctx.config.nonInteractive) { if (!configReady && input.target === undefined && input.install_params === undefined) { throw new ToolError( 'PLAN_INPUT_REQUIRED', 'Installer defaults do not form a complete install plan; provide target/install_params with --input', ) } return inspection } await ctx.io.stderr(`${JSON.stringify(confirmationSummary(inspection), null, 2)}\n`) if (!ctx.io.inputIsTerminal || ctx.confirmed) return inspection const answer = (await ctx.io.prompt('Accept default install plan? [Y/e/n] '))?.trim() .toLowerCase() if (answer === 'n' || answer === 'no') { throw new ToolError( 'CONFIRMATION_DECLINED', 'install plan creation was declined', EXIT_PERMISSION, ) } if (answer === 'e' || answer === 'edit') { const raw = await ctx.io.prompt('Plan choices JSON ({"target":...,"install_params":...}): ') const choices = parsePlanChoices(raw) inspection = await recomputePlan(ctx, source, input, initial.plan, choices) } if (readinessValue(inspection, 'config') !== 'READY') { throw new ToolError( 'PLAN_INPUT_REQUIRED', 'the selected plan still has unresolved configuration requirements', ) } return inspection } async function findInstalled( ctx: CommandContext, appDid: string, ownerUserId?: string, ): Promise | undefined> { try { return expectObject( await callControl(ctx, 'apps.details', { selector: appDid, ...(ownerUserId ? { owner_user_id: ownerUserId } : {}), }), 'apps.details response', ) } catch (error) { if (error instanceof ToolError && error.code === 'RESOURCE_NOT_FOUND') return undefined throw error } } async function observeInstallTask( ctx: CommandContext, taskId: string, ): Promise { const status = expectObject( await callControl(ctx, 'apps.install.status', { task_id: taskId }), 'apps.install.status response', ) const error = isObject(status.error) ? status.error : undefined const sanitizedDetails = error && isObject(error.details) ? sanitizeAppOutput(error.details) : undefined return { phase: expectString(status, 'task_phase'), outcome: optionalString(status.task_outcome), message: installProgressMessage(status), error: error ? { code: optionalString(error.code), message: optionalString(error.message), retryable: typeof error.retryable === 'boolean' ? error.retryable : undefined, details: isObject(sanitizedDetails) ? sanitizedDetails : undefined, } : undefined, data: status, } } async function confirmChange( ctx: CommandContext, action: string, summary: Record, ): Promise { await ctx.io.stderr(`${JSON.stringify({ action, preflight: summary }, null, 2)}\n`) if (ctx.confirmed) return if (ctx.config.nonInteractive || !ctx.io.inputIsTerminal) { throw new ToolError( 'CONFIRMATION_REQUIRED', `${action} requires --yes in non-interactive execution`, EXIT_PERMISSION, ) } const answer = (await ctx.io.prompt(`Proceed with app ${action}? [y/N] `))?.trim().toLowerCase() if (answer !== 'y' && answer !== 'yes') { throw new ToolError('CONFIRMATION_DECLINED', `${action} was declined`, EXIT_PERMISSION) } } async function callControl( ctx: CommandContext, method: string, params: Record, ): Promise { try { return await ctx.clients.call(CONTROL_PANEL_SERVICE, method, params, rpcOptions(ctx)) } catch (error) { throw normalizeAppServiceError(error) } } function normalizeAppServiceError(error: unknown): ToolError { if (error instanceof ToolError) return error const message = errorMessage(error) const structured = parseEmbeddedJson(message) if (structured && typeof structured.code === 'string') { const rawDetails = isObject(structured.details) ? structured.details : structured const details = sanitizeAppOutput(rawDetails) return new ToolError( structured.code, typeof structured.message === 'string' ? structured.message : message, structured.code === 'AMBIGUOUS_APP_TARGET' ? EXIT_OPERATION : EXIT_OPERATION, structured.retryable === true, isObject(details) ? details : {}, ) } const lower = message.toLowerCase() if ( lower.includes('invalid token') || lower.includes('unauthorized') || lower.includes('rpc call error: 401') || lower.includes('session expired') || lower.includes('token expired') ) { return new ToolError( lower.includes('expired') ? 'SESSION_EXPIRED' : 'INVALID_SESSION', lower.includes('expired') ? 'the session token has expired' : message, EXIT_AUTH, ) } if (lower.includes('abort') || lower.includes('cancel')) { return new ToolError('CANCELED', 'operation canceled', EXIT_TIMEOUT) } if (lower.includes('timeout') || lower.includes('timed out')) { return new ToolError('TIMEOUT', 'operation timed out', EXIT_TIMEOUT, true) } if ( lower.includes('fetch failed') || lower.includes('connection refused') || lower.includes('rpc call error: 502') || lower.includes('rpc call error: 503') || lower.includes('rpc call error: 504') ) { return new ToolError('SERVICE_UNAVAILABLE', message, EXIT_UNAVAILABLE, true) } if (message.includes('APP_NOT_INSTALLED') || /not found/i.test(message)) { return new ToolError('RESOURCE_NOT_FOUND', message) } if (/permission|forbidden/i.test(message)) { return new ToolError('PERMISSION_DENIED', message, EXIT_PERMISSION) } if (/rolling restart is not supported/i.test(message)) { return new ToolError('UNSUPPORTED_STRATEGY', message) } return new ToolError('OPERATION_FAILED', message, EXIT_OPERATION) } function sourceRpcParams(source: PreparedSource): Record { return { source: source.serviceSource } } function scopeAndChoiceParams(input: Record): Record { return { ...(typeof input.owner_user_id === 'string' ? { owner_user_id: input.owner_user_id } : {}), ...(isObject(input.target) ? { target: input.target } : {}), ...(isObject(input.install_params) ? { install_params: input.install_params } : {}), } } function planScopeAndOptions(plan: Record): Record { return { owner_user_id: expectString(plan, 'owner_user_id'), target: expectObject(plan.target, 'plan.target'), install_params: expectObject(plan.install_params, 'plan.install_params'), } } function installedScope(details: Record): Record { return { owner_user_id: expectString(details, 'owner_user_id'), } } function installOptions(input: Record): Record { const policy = optionalString(input.policy) ?? 'normal' return { policy: policy.replaceAll('-', '_').toUpperCase() } } function sourceSummary(source: PreparedSource): Record { if (source.kind === 'catalog') return { kind: source.kind, identifier: source.display } return { kind: source.kind, source: source.display, pikg_digest: source.snapshot.digest, size: source.snapshot.size, } } function confirmationSummary(inspection: InstallInspection): Record { const plan = inspection.plan return { plan_fingerprint: plan.plan_fingerprint, plan_use: plan.plan_use, app: plan.app, app_instance_id: plan.app_instance_id, owner_user_id: plan.owner_user_id, target: plan.target, selected_packages: plan.selected_packages, install_params: plan.install_params, readiness: inspection.status.readiness, warnings: inspection.status.warnings ?? [], } } function satisfiedResult(inspection: InstallInspection): Record { return { action: 'satisfied', task_id: null, app_instance_id: inspection.plan.app_instance_id, app_doc_object_id: expectObject(inspection.plan.app, 'plan.app').object_id, } } function assertPlanMatchesInspection( plan: Record, inspection: InstallInspection, ): void { const fingerprint = expectString(plan, 'plan_fingerprint') if (fingerprint !== inspection.plan.plan_fingerprint) { throw new ToolError( 'PLAN_STALE', 'the plan no longer matches the authoritative source, scope, target, or configuration', EXIT_OPERATION, false, { plan_fingerprint: fingerprint, current_fingerprint: inspection.plan.plan_fingerprint, }, ) } } function verifyPikgBinding( source: PreparedSource, plan: Record, ): void { if (source.kind === 'catalog') return const identity = expectObject(plan.source_identity, 'plan.source_identity') const digest = expectString(identity, 'pikg_digest') if (digest !== source.snapshot.digest) { throw new ToolError( 'PLAN_STALE', 'the PIKG byte snapshot does not match the plan source digest', EXIT_OPERATION, false, { plan_digest: digest, source_digest: source.snapshot.digest }, ) } } function assertPortablePlan(plan: Record): void { if (plan.schema_version !== PLAN_SCHEMA_VERSION) { throw new ToolError( 'UNSUPPORTED_SCHEMA_VERSION', `InstallPlan schema must be v${PLAN_SCHEMA_VERSION}`, ) } expectString(plan, 'plan_fingerprint') expectString(plan, 'task_id') const allowed = new Set([ 'schema_version', 'plan_use', 'task_id', 'app_instance_id', 'owner_user_id', 'source_identity', 'app', 'app_doc', 'resolution', 'target', 'selected_packages', 'required_contents', 'install_params', 'service_spec_config', 'plan_fingerprint', 'created_at', ]) for (const key of Object.keys(plan)) { if (!allowed.has(key)) { throw new ToolError('PLAN_STALE', `InstallPlan contains an unknown field: ${key}`) } } assertNoPlanSecrets(plan, 'plan') } function assertNoPlanSecrets(value: unknown, path: string): void { if (Array.isArray(value)) { value.forEach((item, index) => assertNoPlanSecrets(item, `${path}[${index}]`)) return } if (!isObject(value)) return for (const [key, child] of Object.entries(value)) { const normalized = key.toLowerCase() const disallowed = normalized === 'staging_handle' || normalized === 'staging_path' || normalized === 'session_token' || normalized === 'refresh_token' || normalized === 'private_key' || normalized === 'password' || normalized.endsWith('_token') || normalized.endsWith('_password') || normalized.endsWith('_private_key') || (normalized.endsWith('secret') && normalized !== 'secret_ref') if (disallowed) { throw new ToolError('INVALID_PLAN_SECRET', `${path}.${key} is forbidden in InstallPlan`) } if ( typeof child === 'string' && (/^[a-z][a-z0-9+.-]*:\/\/[^\s/@:]+:[^\s/@]+@/i.test(child) || /^(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\//i.test(child)) ) { throw new ToolError( 'INVALID_PLAN_SECRET', `${path}.${key} contains a connection string; use SecretRef`, ) } assertNoPlanSecrets(child, `${path}.${key}`) } } async function readPlanFile(path: string): Promise> { let raw: string try { raw = await getHost().readTextFile(path) } catch (error) { throw new UsageError('PLAN_READ_FAILED', `failed to read InstallPlan: ${errorMessage(error)}`) } let value: unknown try { value = JSON.parse(raw) } catch { throw new UsageError('INVALID_PLAN_JSON', 'InstallPlan is not valid JSON') } const plan = expectObject(value, 'InstallPlan') assertPortablePlan(plan) return plan } async function writePlanFile( ctx: CommandContext, path: string, plan: Record, ): Promise { const exists = await tryLstat(path) if (exists) { if (!exists.isFile) { throw new UsageError('INVALID_PLAN_PATH', 'InstallPlan destination is not a regular file') } if (!ctx.confirmed) { if (ctx.config.nonInteractive || !ctx.io.inputIsTerminal) { throw new ToolError( 'CONFIRMATION_REQUIRED', `InstallPlan already exists: ${path}; use --yes to overwrite it`, EXIT_PERMISSION, ) } const answer = (await ctx.io.prompt(`Overwrite existing InstallPlan ${path}? [y/N] `)) ?.trim().toLowerCase() if (answer !== 'y' && answer !== 'yes') { throw new ToolError( 'CONFIRMATION_DECLINED', 'InstallPlan overwrite was declined', EXIT_PERMISSION, ) } } } const content = `${JSON.stringify(plan, null, 2)}\n` try { await getHost().writeTextFile( path, content, exists ? { mode: 0o600 } : { createNew: true, mode: 0o600 }, ) if (getHost().platform !== 'windows') await getHost().chmod(path, 0o600) } catch (error) { throw new UsageError('PLAN_WRITE_FAILED', `failed to write InstallPlan: ${errorMessage(error)}`) } } async function releaseStaging(ctx: CommandContext, source: PreparedSource): Promise { if (source.kind === 'catalog') return try { await ctx.clients.call( CONTROL_PANEL_SERVICE, 'apps.staging.release', { staging_handle: source.staging.handle }, { traceId: ctx.traceId, timeoutMs: STAGING_RELEASE_TIMEOUT_MS, signal: new AbortController().signal, }, ) } catch (error) { await ctx.io.stderr(`warning: failed to release PIKG staging lease: ${errorMessage(error)}\n`) } } function expectInspection(value: unknown): InstallInspection { const object = expectObject(value, 'apps.inspect response') const schemaVersion = expectNumber(object, 'schema_version') if (schemaVersion !== PLAN_SCHEMA_VERSION) { throw new ToolError( 'UNSUPPORTED_SCHEMA_VERSION', `Installer returned schema v${schemaVersion}; v${PLAN_SCHEMA_VERSION} is required`, ) } const inspection: InstallInspection = { schema_version: schemaVersion, plan: expectObject(object.plan, 'inspection.plan'), resolution_status: expectObject(object.resolution_status, 'inspection.resolution_status'), status: expectObject(object.status, 'inspection.status'), } assertPortablePlan(inspection.plan) if (inspection.status.plan_fingerprint !== inspection.plan.plan_fingerprint) { throw new ToolError('INVALID_SERVICE_RESPONSE', 'inspection fingerprint fields disagree', 9) } return inspection } function parsePlanChoices(raw: string | null | undefined): Record { if (!raw) throw new ToolError('PLAN_INPUT_REQUIRED', 'plan choices JSON is required') let value: unknown try { value = JSON.parse(raw) } catch { throw new UsageError('INVALID_INPUT_JSON', 'plan choices are not valid JSON') } const choices = expectObject(value, 'plan choices') for (const key of Object.keys(choices)) { if (key !== 'target' && key !== 'install_params') { throw new UsageError('INVALID_ARGUMENT', `unknown plan choice: ${key}`) } } return choices } function normalizeCatalogIdentifier(value: string): string { const raw = value.trim() if ( !raw || /^https?:\/\//i.test(raw) || raw.includes('/') || raw.includes('\\') || /\s/.test(raw) ) { throw new UsageError('INVALID_APP_NAME', `invalid Catalog App identifier: ${value}`) } if (raw.startsWith('did:')) { return parseAppDid(raw) } return raw.includes('.') ? raw.toLowerCase() : parseAppDid(`did:bns:${raw}`) } function normalizeAppSelector(value: string): string { return normalizeCatalogIdentifier(value) } function parseAppDid(raw: string): string { let did: InstanceType try { did = namelib.DID.fromStr(raw) } catch (error) { throw new UsageError('INVALID_APP_DID', `invalid App DID: ${errorMessage(error)}`) } if (did.method === 'key' || did.method === 'dev') { throw new UsageError('INVALID_APP_DID', 'key-class DIDs cannot identify an App') } return did.toString() } function parsePikgUrl(value: string): URL { let url: URL try { url = new URL(value) } catch { throw new UsageError('INVALID_PIKG_URL', `invalid PIKG URL: ${value}`) } if (url.protocol !== 'http:' && url.protocol !== 'https:') { throw new UsageError('INVALID_PIKG_URL', 'PIKG URL must use HTTP or HTTPS') } if (url.username || url.password) { throw new UsageError('INVALID_PIKG_URL', 'PIKG URL must not contain credentials') } return url } function validatePikgSnapshot(bytes: Uint8Array): void { if (bytes.length < ZIP_LOCAL_MAGIC.length) { throw new UsageError('INVALID_PIKG', 'PIKG is too small to be a ZIP container') } if (!ZIP_LOCAL_MAGIC.every((byte, index) => bytes[index] === byte)) { throw new UsageError('INVALID_PIKG', 'PIKG magic mismatch: expected a ZIP container') } } function gatewayOrigin(endpoint: string): string { const url = new URL(endpoint) const marker = url.pathname.indexOf('/kapi') url.pathname = marker >= 0 ? url.pathname.slice(0, marker) || '/' : '/' url.search = '' url.hash = '' return url.toString().replace(/\/$/, '') } function safeUrl(url: URL): string { const safe = new URL(url) safe.search = '' safe.hash = '' return safe.toString() } function looksLikeLocalPath(value: string): boolean { return value.includes('/') || value.includes('\\') || value.startsWith('.') || value.toLowerCase().endsWith('.pikg') } async function tryLstat(path: string): Promise { try { return await getHost().lstat(path) } catch (error) { if (isHostError(error, 'NotFound')) return undefined throw new UsageError('FILE_ACCESS_FAILED', `failed to inspect ${path}: ${errorMessage(error)}`) } } function resolveFromCwd(ctx: CommandContext, path: string): string { return isAbsolute(path) ? resolve(path) : resolve(ctx.cwd, path) } function parseEmbeddedJson(message: string): Record | undefined { for (let index = message.indexOf('{'); index >= 0; index = message.indexOf('{', index + 1)) { try { const value = JSON.parse(message.slice(index)) if (isObject(value)) return value } catch { // Try the next opening brace; kRPC prefixes structured service errors. } } return undefined } function readinessValue(inspection: InstallInspection, field: string): string | undefined { const readiness = isObject(inspection.status.readiness) ? inspection.status.readiness : undefined return readiness ? optionalString(readiness[field]) : undefined } function planUse(plan: Record): string | undefined { return optionalString(plan.plan_use) } function installProgressMessage(status: Record): string | undefined { const stage = optionalString(status.stage) const progress = isObject(status.progress) ? status.progress : undefined const percent = progress && typeof progress.percent === 'number' ? `${progress.percent}%` : undefined return [stage, percent].filter(Boolean).join(' ') || undefined } function idempotencyKey(ctx: CommandContext): string { return ctx.idempotencyKey ?? crypto.randomUUID() } function rejectDryRunNoWait(input: Record): void { if (input.dry_run === true && input.no_wait === true) { throw new UsageError('ARGUMENT_CONFLICT', '--dry-run and --no-wait are mutually exclusive') } } function selectorCommand(options: { verb: string summary: string access: 'read' | 'write' | 'destructive' asyncMode: 'sync' | 'task' | 'either' handler: CommandDefinition['handler'] }): CommandDefinition { return { verb: options.verb, summary: options.summary, positionals: [{ name: 'app_name', description: 'Installed App name or DID' }], inputSchema: { type: 'object', properties: { app_name: { type: 'string', minLength: 1 } }, required: ['app_name'], additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: options.access }, asyncMode: options.asyncMode, requiresSession: true, examples: [`buckyos app ${options.verb} app1`], handler: options.handler, } } function sourceOptions( extra: NonNullable, ): NonNullable { return [ { name: 'from', description: 'Force source type', type: 'string', enum: ['catalog', 'pikg', 'url'], }, { name: 'pikg', description: 'Explicit local PIKG path', type: 'string' }, ...extra, ] } function sourceInputSchema(extra: Record): JsonSchema { return { type: 'object', properties: { source: { type: 'string', minLength: 1 }, from: { type: 'string', enum: ['catalog', 'pikg', 'url'] }, pikg: { type: 'string', minLength: 1 }, ...extra, }, additionalProperties: false, } } function emptyInputSchema(): JsonSchema { return { type: 'object', properties: {}, additionalProperties: false } } function ownerOption(): NonNullable[number] { return { name: 'owner', property: 'owner_user_id', description: 'Installation owner user', type: 'string', } } function policyOption(): NonNullable[number] { return { name: 'policy', description: 'Installer trust policy', type: 'string', enum: [...INSTALL_POLICIES], } } function rpcOptions(ctx: CommandContext): { traceId: string timeoutMs: number signal: AbortSignal } { return { traceId: ctx.traceId, timeoutMs: Math.max(1, (ctx.deadline ?? Date.now()) - Date.now()), signal: ctx.signal, } } function expectObject(value: unknown, label: string): Record { if (!isObject(value)) { throw new ToolError('INVALID_SERVICE_RESPONSE', `${label} must be an object`, EXIT_INTERNAL) } return value } function isObject(value: unknown): value is Record { return !!value && typeof value === 'object' && !Array.isArray(value) } function expectString(object: Record, property: string): string function expectString(value: unknown, property: string): string function expectString(value: unknown, property: string): string { const candidate = isObject(value) ? value[property] : value if (typeof candidate !== 'string' || !candidate.trim()) { throw new ToolError('INVALID_SERVICE_RESPONSE', `${property} must be a non-empty string`, 9) } return candidate } function expectNumber(object: Record, property: string): number { const value = object[property] if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) { throw new ToolError('INVALID_SERVICE_RESPONSE', `${property} must be a non-negative integer`, 9) } return value } function optionalString(value: unknown): string | undefined { return typeof value === 'string' && value.trim() ? value : undefined } function optionalNumber(value: unknown): number | undefined { return typeof value === 'number' && Number.isFinite(value) ? value : undefined } function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error) } function sanitizeAppOutput(value: unknown): unknown { if (Array.isArray(value)) return value.map(sanitizeAppOutput) if (!isObject(value)) return value const result: Record = {} const forbidden = new Set([ 'spec_path', 'staging_handle', 'staging_path', 'source_url', 'session_token', 'refresh_token', 'private_key', 'password', 'connection_string', 'database_url', ]) for (const [key, child] of Object.entries(value)) { if (!forbidden.has(key.toLowerCase())) result[key] = sanitizeAppOutput(child) } return result }