import type { CommandContext } from '../core/context.ts' import type { CommandModule } from '../core/command.ts' import { EXIT_PERMISSION, EXIT_UNAVAILABLE, ToolError, UsageError } from '../core/errors.ts' import { AIWS_MANIFEST_FILE, AIWS_MANIFEST_VERSION, aiwsContentDigest, controlSkeleton } from 'buckyos/node' import { createDeterministicTarGz, digestFile, sha256Bytes } from './pikg_archive.ts' import { APPDOC_ENTRY, appDocObjectId, assertSelectorCompatible, canonicalSelector, createPackageMeta, deriveAppNamespace, derivedSelector, DIST_MANIFEST_NAME, expectNonEmptyString, expectObject, EXT_TOOLS_MANIFEST_FILE, EXT_TOOLS_MANIFEST_SCHEMA, EXT_TOOLS_PLATFORMS, extToolsManifestErrors, extToolsPayloadErrors, extToolsPlatformOfKey, type ExtToolsManifest, type ExtToolsPayloadTree, inspectPikg, normalizeArch, PACKAGE_META_ENTRY, PACKAGE_META_SCHEMA, type PackageMetaFile, packSnapshot, parsePackageMeta, rejectUnknown, stableJsonDigest, validatePermissions, validateAppPresentation, validateContentHandlers, validateServiceConfigTips, validateSnapshot, validateSubpackageName, } from './pikg_protocol.ts' import { distributionManifestView, getHost, type HostFileInfo, isHostError, policyView, readDistributionManifest, } from '../runtime/host.ts' import { PROTOCOL_VERSION, SDK_VERSION, TOOL_VERSION } from '../version.ts' import { identityCandidateView } from '../core/identity.ts' const basename = (path: string) => getHost().path.basename(path) const dirname = (path: string) => getHost().path.dirname(path) const isAbsolute = (path: string) => getHost().path.isAbsolute(path) const join = (...parts: string[]) => getHost().path.join(...parts) const relative = (from: string, to: string) => getHost().path.relative(from, to) const resolve = (...parts: string[]) => getHost().path.resolve(...parts) const APP_DOCUMENT_LIFETIME_SECONDS = 5 * 365 * 24 * 60 * 60 const SAFE_PIKG_FILE = /^[A-Za-z0-9._-]+\.pikg$/ const APP_NAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/ const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/ const SHA256_ID = /^sha256:[0-9a-f]{64}$/ const OBJECT_ID = /^(?:appdoc|pkg):[0-9a-f]{64}$/ const SAFE_GENERATED_FILE = /^[A-Za-z0-9._-]+$/ const OBJECT_OUTPUT = { type: 'object' as const, additionalProperties: true } const APP_KINDS = ['static-web', 'script', 'docker', 'agent-skills', 'aiws-controls', 'ext-tools'] const PATH_KINDS: Record = { 'static-web': { key: 'web', category: 'web', selectorType: 'static' }, script: { key: 'script', category: 'dapp', selectorType: 'single' }, 'agent-skills': { key: 'agent_skills', category: 'agent_skills', selectorType: 'single' }, // AI Workspace controls: one bundle (aiws-manifest.json + controls//), installed into the AI Workspace library 'aiws-controls': { key: 'aiws', category: 'aiws', selectorType: 'single' }, // Extension tools: ext-manifest.json + payload//, one sub package per platform, enabled for the Zone 'ext-tools': { key: 'ext_tools', category: 'ext_tools', selectorType: 'single' }, } const EXT_TOOLS_LAUNCHER_LIMIT = 1024 * 1024 export interface DockerImageInfo { id: string architecture: string canonicalName: string } export interface DockerClient { inspect(reference: string): Promise save(imageId: string, destinationTarGz: string): Promise } export interface PikgModuleDependencies { docker?: DockerClient now?: () => number } interface AppMeta { schema_version: 1 did: string name: string version: string owner: string author: string show_name: string presentation?: Record categories: string[] permissions: unknown[] content_handlers?: unknown[] selector_type: string service_config_tips: Record } interface PathSource { type: 'path' path: string } interface DockerSource { type: 'docker-image' image: string } interface SubpackageInput { selector?: Record required: boolean source: PathSource | DockerSource } interface PikgMeta { schema_version: 1 output_dir: string pikg_file: string sub_pkgs: Record } interface GeneratedFileRecord { size: number digest: string } interface DistManifest { schema_version: 1 tool_version: string meta_root_id: string source_fingerprint: string app_doc_object_id: string pikg_file: string generated_files: Record subpackages: Record< string, { source_kind: string; size: number; digest: string; pkg_objid: string } > } interface PreparedSubpackage { key: string input: SubpackageInput payloadPath: string digest: GeneratedFileRecord docker?: DockerImageInfo } function packageEnvironmentQualifier( key: string, selector: Record | undefined, ): string { const effective = selector ?? derivedSelector(key) const os = effective?.os const arch = effective?.arch if (!os || !arch) return 'all' const environmentOs = os === 'macos' ? 'apple' : os const environmentArch = arch === 'x86_64' ? 'amd64' : arch const qualifier = `nightly-${environmentOs}-${environmentArch}` return new Set([ 'nightly-linux-amd64', 'nightly-linux-aarch64', 'nightly-windows-amd64', 'nightly-windows-aarch64', 'nightly-apple-amd64', 'nightly-apple-aarch64', ]).has(qualifier) ? qualifier : 'all' } export function createPikgModule(dependencies: PikgModuleDependencies = {}): CommandModule { const docker = dependencies.docker ?? new LocalDockerClient() const now = dependencies.now ?? reproducibleBuildTimestamp return { name: 'pikg', summary: 'Build and verify local PIKG release candidates', commands: [ { verb: 'doctor', summary: 'Inspect the local SDK, Tool, host policy, metadata, and target profile', positionals: [ { name: 'meta_dir', description: 'dapp_meta directory', required: false }, ], options: [ { name: 'catalog', description: 'ext-tools: a directory of other packages (/ext-manifest.json) to check requires and same-named commands against', type: 'string', }, ], inputSchema: { type: 'object', properties: { meta_dir: { type: 'string', minLength: 1 }, catalog: { type: 'string', minLength: 1 }, }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'read' }, asyncMode: 'sync', requiresSession: false, execution: 'local', networkAccess: false, examples: [ 'buckyos pikg doctor', 'buckyos pikg doctor ./dapp_meta', 'buckyos pikg doctor ./dapp_meta --catalog ../publish/exttool', ], handler: async (ctx, input) => await doctorCommand(ctx, input), }, { verb: 'init', summary: 'Create local PIKG development metadata', description: 'Creates only dapp_meta/app.json and dapp_meta/pikg.json.', positionals: [ { name: 'project_dir', description: 'Existing App project directory', required: false }, ], options: [ { name: 'name', description: 'App name', type: 'string' }, { name: 'owner', description: 'Owner DID', type: 'string' }, { name: 'kind', description: 'Initial App kind', type: 'string', enum: APP_KINDS, }, { name: 'source', description: 'Build output path or local Docker image', type: 'string', }, { name: 'version', description: 'Initial App version', type: 'string' }, { name: 'app-did', property: 'app_did', description: 'Explicit App DID', type: 'string' }, { name: 'composite', description: 'aiws-controls: start the package with a composite control (a panel of Blocks) instead of a declarative one', type: 'boolean', }, ], inputSchema: { type: 'object', properties: { project_dir: { type: 'string', minLength: 1 }, name: { type: 'string', minLength: 1 }, owner: { type: 'string', minLength: 1 }, kind: { type: 'string', enum: APP_KINDS }, source: { type: 'string', minLength: 1 }, version: { type: 'string', minLength: 1 }, app_did: { type: 'string', minLength: 1 }, composite: { type: 'boolean' }, }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'sync', requiresSession: false, execution: 'local', networkAccess: false, examples: [ 'buckyos pikg init .', 'buckyos --non-interactive pikg init . --owner did:bns:root --kind static-web --source ./web/dist', 'buckyos --non-interactive pikg init . --owner did:bns:root --kind agent-skills --source ./skills', 'buckyos --non-interactive pikg init . --owner did:bns:alice --kind aiws-controls --source ./aiws', 'buckyos --non-interactive pikg init . --owner did:bns:alice --kind aiws-controls --source ./aiws --composite', 'buckyos --non-interactive pikg init . --name ext-media --owner did:bns:root --kind ext-tools --source ./ext-media', ], handler: async (ctx, input) => await initCommand(ctx, input, docker), }, { verb: 'build', summary: 'Build a managed dapp_dist snapshot', positionals: [ { name: 'meta_dir', description: 'dapp_meta directory', required: false }, ], inputSchema: { type: 'object', properties: { meta_dir: { type: 'string', minLength: 1 } }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'sync', requiresSession: false, execution: 'local', networkAccess: false, examples: ['buckyos pikg build ./dapp_meta'], handler: async (ctx, input) => await buildCommand(ctx, input, docker, now), }, { verb: 'pack', summary: 'Pack and verify a complete PIKG', positionals: [ { name: 'dist_dir', description: 'Managed dapp_dist directory', required: false }, ], inputSchema: { type: 'object', properties: { dist_dir: { type: 'string', minLength: 1 } }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'write' }, asyncMode: 'sync', requiresSession: false, execution: 'local', networkAccess: false, examples: ['buckyos pikg pack ./dapp_dist'], handler: async (ctx, input) => await packCommand(ctx, input), }, { verb: 'info', summary: 'Strictly verify and inspect a local PIKG', positionals: [{ name: 'pikg_path', description: 'Local .pikg file' }], inputSchema: { type: 'object', properties: { pikg_path: { type: 'string', minLength: 1 } }, required: ['pikg_path'], additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'read' }, asyncMode: 'sync', requiresSession: false, execution: 'local', networkAccess: false, examples: ['buckyos pikg info ./dapp_dist/demo-0.1.0.pikg'], handler: async (ctx, input) => await inspectPikg(resolveFromCwd(ctx, expectInputString(input, 'pikg_path'))), }, { verb: 'clean', summary: 'Safely delete a managed dapp_dist', positionals: [ { name: 'meta_dir', description: 'dapp_meta directory', required: false }, ], inputSchema: { type: 'object', properties: { meta_dir: { type: 'string', minLength: 1 } }, additionalProperties: false, }, outputSchema: OBJECT_OUTPUT, resultSchemaVersion: 1, access: { mode: 'fixed', level: 'destructive' }, asyncMode: 'sync', requiresSession: false, execution: 'local', networkAccess: false, examples: ['buckyos --non-interactive --yes pikg clean ./dapp_meta'], handler: async (ctx, input) => await cleanCommand(ctx, input), }, ], } } function reproducibleBuildTimestamp(): number { const configured = getHost().env('SOURCE_DATE_EPOCH') if (configured === undefined) return Math.floor(Date.now() / 1000) if (!/^\d+$/.test(configured)) { throw new UsageError( 'INVALID_SOURCE_DATE_EPOCH', 'SOURCE_DATE_EPOCH must be a non-negative integer number of seconds', ) } const seconds = Number(configured) if (!Number.isSafeInteger(seconds)) { throw new UsageError( 'INVALID_SOURCE_DATE_EPOCH', 'SOURCE_DATE_EPOCH is outside the supported integer range', ) } return seconds } async function doctorCommand( ctx: CommandContext, input: Record, ): Promise> { const metaInput = optionalInputString(input, 'meta_dir') ?? './dapp_meta' const metaDir = resolveFromCwd(ctx, metaInput) const checks: Array> = [] let appMeta: Record | undefined let pikgMeta: Record | undefined for ( const [name, path] of [ ['app_metadata', join(metaDir, 'app.json')], ['pikg_metadata', join(metaDir, 'pikg.json')], ] as const ) { try { const value = await readJson(path, name) if (name === 'app_metadata') appMeta = value else pikgMeta = value checks.push({ name, status: 'ok', path }) } catch (error) { checks.push({ name, status: isHostError(error, 'NotFound') ? 'missing' : 'error', path, detail: error instanceof Error ? error.message : String(error), }) } } if (appMeta && pikgMeta) { try { const app = parseAppMeta(appMeta) const pikg = parsePikgMeta(pikgMeta, app) const missingSources: string[] = [] for (const subpackage of Object.values(pikg.sub_pkgs)) { if (subpackage.source.type !== 'path') continue const source = resolve(metaDir, subpackage.source.path) try { await getHost().lstat(source) } catch (error) { if (isHostError(error, 'NotFound')) missingSources.push(source) else throw error } } checks.push({ name: 'build_outputs', status: missingSources.length === 0 ? 'ok' : 'missing', missing: missingSources, }) if (app.categories[0] === PATH_KINDS['ext-tools'].category) { const catalog = optionalInputString(input, 'catalog') checks.push(...await extToolsChecks(app, pikg, metaDir, catalog ? resolveFromCwd(ctx, catalog) : undefined)) } } catch (error) { checks.push({ name: 'metadata_schema', status: 'error', detail: error instanceof Error ? error.message : String(error), }) } } const globalConfig = await ctx.configStore.readConfig() const profileName = ctx.config.profileName ?? globalConfig.default_profile const profile = profileName ? await ctx.configStore.readProfile(profileName) : undefined const host = getHost() return { healthy: checks.every((check) => check.status === 'ok' || check.status === 'skipped'), tool_version: TOOL_VERSION, sdk_version: SDK_VERSION, protocol_version: PROTOCOL_VERSION, ...policyView(host), distribution_manifest: distributionManifestView(await readDistributionManifest(host)), target: { profile: profileName ?? null, zone: ctx.config.zone ?? profile?.zone ?? null, endpoint: ctx.config.endpoint ?? profile?.endpoint ?? null, compatibility: 'not-checked', }, identity_candidates: await identityCandidateView(ctx.config), checks, } } async function initCommand( ctx: CommandContext, input: Record, docker: DockerClient, ): Promise> { const projectInput = optionalInputString(input, 'project_dir') ?? '.' const projectDir = await realDirectory(resolveFromCwd(ctx, projectInput), 'project directory') let name = optionalInputString(input, 'name') ?? normalizeAppName(basename(projectDir)) const canPrompt = !ctx.config.nonInteractive && !ctx.interactive && ctx.io.inputIsTerminal if (!name) name = await requiredPrompt(ctx, canPrompt, 'App name: ', 'name') let owner = optionalInputString(input, 'owner') if (!owner) owner = await requiredPrompt(ctx, canPrompt, 'Owner DID: ', 'owner') let kind = optionalInputString(input, 'kind') if (!kind) { kind = await requiredPrompt( ctx, canPrompt, `App kind (${APP_KINDS.join('/')}): `, 'kind', ) } if (!APP_KINDS.includes(kind)) { throw new UsageError('INVALID_APP_KIND', `invalid App kind: ${kind}`) } let source = optionalInputString(input, 'source') if (!source) source = await requiredPrompt(ctx, canPrompt, 'Source: ', 'source') const version = optionalInputString(input, 'version') ?? '0.1.0' validateAppName(name) validateVersion(version) const derivedDid = deriveAppDid(name, owner) const appDid = optionalInputString(input, 'app_did') ?? derivedDid deriveAppNamespace(appDid) let subpackageKey: string let sourceValue: Record let selector: Record | undefined let sourceSummary: Record if (kind === 'ext-tools') { const platform = hostExtToolsPlatform() const absoluteSource = resolve(projectDir, source) subpackageKey = platform.key selector = platform.selector sourceValue = { type: 'path', path: toPortablePath(relative(join(projectDir, 'dapp_meta'), join(absoluteSource, 'payload', platform.name))), } sourceSummary = { type: 'path', path: displaySource(projectDir, absoluteSource), platform: platform.name } try { await getHost().lstat(join(absoluteSource, EXT_TOOLS_MANIFEST_FILE)) } catch (error) { if (!isHostError(error, 'NotFound')) throw error await writeExtToolsSkeleton(absoluteSource, name, version, platform.name) sourceSummary.skeleton = true } } else if (kind === 'docker') { const image = await docker.inspect(source) const arch = normalizeArch(image.architecture) subpackageKey = arch === 'x86_64' ? 'amd64_docker_image' : arch === 'aarch64' ? 'aarch64_docker_image' : (() => { throw new UsageError('UNSUPPORTED_ARCHITECTURE', `unsupported Docker architecture: ${arch}`) })() selector = { os: 'linux', arch } sourceValue = { type: 'docker-image', image: source } sourceSummary = { type: 'docker-image', image: image.canonicalName, image_id: image.id } } else { subpackageKey = PATH_KINDS[kind].key const absoluteSource = resolve(projectDir, source) const persistedSource = isAbsolute(source) ? resolve(source) : toPortablePath(relative(join(projectDir, 'dapp_meta'), absoluteSource)) sourceValue = { type: 'path', path: persistedSource } sourceSummary = { type: 'path', path: displaySource(projectDir, absoluteSource) } try { await getHost().lstat(absoluteSource) } catch (error) { if (!isHostError(error, 'NotFound')) throw error if (kind === 'aiws-controls') { await writeAiwsSkeleton(absoluteSource, owner, name, input.composite === true) sourceSummary.skeleton = true } else { await ctx.io.stderr(`warning: source does not exist yet: ${sourceSummary.path}\n`) } } } const appMeta: AppMeta = { schema_version: 1, did: appDid, name, version, owner, author: owner, show_name: name, categories: [PATH_KINDS[kind]?.category ?? 'dapp'], permissions: [], selector_type: PATH_KINDS[kind]?.selectorType ?? 'single', service_config_tips: {}, } const pikgMeta = { schema_version: 1, output_dir: '../dapp_dist', pikg_file: `${name}-${version}.pikg`, sub_pkgs: { [subpackageKey]: { ...(selector ? { selector } : {}), required: true, source: sourceValue, }, }, } parseAppMeta({ ...appMeta }) parsePikgMeta(pikgMeta) const metaDir = join(projectDir, 'dapp_meta') await initializeMetaDirectory(projectDir, metaDir, appMeta, pikgMeta) return { project_dir: projectDir, meta_dir: metaDir, generated_files: [join(metaDir, 'app.json'), join(metaDir, 'pikg.json')], app: { did: appDid, name, version, owner, author: owner, show_name: name, categories: appMeta.categories, permissions: [], selector_type: appMeta.selector_type, service_config_tips: {}, }, subpackage: { key: subpackageKey, kind, source: sourceSummary, required: true, ...(selector ? { selector } : {}), }, output_dir: join(projectDir, 'dapp_dist'), pikg_file: pikgMeta.pikg_file, next_command: `buckyos pikg build ${metaDir}`, } } /** A control package skeleton: one declarative control (or a composite one) under controls// and its manifest * (digest included). */ async function writeAiwsSkeleton(dir: string, ownerDid: string, name: string, composite: boolean): Promise { const kind = composite ? 'composite' : 'declarative' const files = controlSkeleton({ authorDid: ownerDid, name, title: name, kind }) const encoder = new TextEncoder() const host = getHost() await host.mkdir(join(dir, 'controls', name), { recursive: true }) for (const [file, text] of Object.entries(files)) await host.writeTextFile(join(dir, 'controls', name, file), text) const digest = await aiwsContentDigest(Object.entries(files).map(([file, text]) => [file, encoder.encode(text)] as [string, Uint8Array])) const manifest = { manifest_version: AIWS_MANIFEST_VERSION, purpose: 'aiws', host_api: composite ? {} : { declarative: 1 }, controls: [{ ident: `${ownerDid}#${name}`, name, kind, version: 1, digest, dir: `controls/${name}/`, title: name }], workspace_templates: [], } await host.writeTextFile(join(dir, AIWS_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`) } function hostExtToolsPlatform(): (typeof EXT_TOOLS_PLATFORMS)[number] { const host = getHost() const os = host.platform === 'darwin' ? 'macos' : host.platform === 'win32' ? 'windows' : host.platform const arch = normalizeArch(host.arch) const platform = EXT_TOOLS_PLATFORMS.find((known) => known.selector.os === os && known.selector.arch === arch) if (!platform) { throw new UsageError('UNSUPPORTED_PLATFORM', `extension packages have no payload for ${os}/${arch}`) } return platform } /** An extension package skeleton for this machine's platform: `ext-manifest.json` and one command that runs and has a * smoke script, so the package builds from the first minute. Other platforms are added beside it. */ async function writeExtToolsSkeleton(dir: string, id: string, version: string, platform: string): Promise { const host = getHost() const manifest = { schema: EXT_TOOLS_MANIFEST_SCHEMA, id, version, requires: [], conflicts: [], provides: [{ command: id, version_probe: `${id} --version`, smoke: `smoke/${id}.sh` }], platforms: [platform], license: '', desc: '', } const text = `${JSON.stringify(manifest, null, 2)}\n` const payload = join(dir, 'payload', platform) for (const sub of ['bin', 'smoke', join('store', id)]) await host.mkdir(join(payload, sub), { recursive: true }) await host.writeTextFile(join(dir, EXT_TOOLS_MANIFEST_FILE), text) await host.writeTextFile(join(payload, EXT_TOOLS_MANIFEST_FILE), text) const windows = platform.startsWith('windows-') await host.writeTextFile( join(payload, 'bin', windows ? `${id}.cmd` : id), windows ? `@echo off\r\necho ${id} ${version}\r\n` : `#!/bin/sh\necho "${id} ${version}"\n`, { mode: 0o755 }, ) await host.writeTextFile( join(payload, 'smoke', windows ? `${id}.ps1` : `${id}.sh`), windows ? `$ErrorActionPreference = 'Continue'\n& ${id} --version | Out-Null\nif ($LASTEXITCODE -ne 0) { exit 1 }\n` : `#!/bin/sh\nset -eu\n${id} --version >/dev/null\n`, { mode: 0o755 }, ) } async function readExtToolsManifestFile(path: string): Promise<{ text: string; manifest?: ExtToolsManifest; errors: string[] }> { let text: string try { text = await getHost().readTextFile(path) } catch (error) { if (isHostError(error, 'NotFound')) return { text: '', errors: ['not found'] } throw error } let value: unknown try { value = JSON.parse(text) } catch { return { text, errors: ['not valid JSON'] } } const errors = extToolsManifestErrors(value) if (errors.length > 0) return { text, errors } const manifest = value as ExtToolsManifest manifest.requires ??= [] manifest.conflicts ??= [] return { text, manifest, errors } } /** A payload directory as `pikg build` would archive it: symlinks read through, and refused when they leave the tree. */ async function readExtToolsPayloadTree(root: string): Promise<{ tree: ExtToolsPayloadTree; errors: string[] }> { const host = getHost() const tree: ExtToolsPayloadTree = { files: new Map(), directories: new Set(), launchers: new Map() } const errors: string[] = [] const realRoot = await host.realPath(root) const walk = async (directory: string, prefix: string): Promise => { const children = await host.readDir(directory) for (const child of children) { const archivePath = prefix ? `${prefix}/${child.name}` : child.name const path = join(directory, child.name) const link = await host.lstat(path) let physical = path if (link.isSymlink) { try { physical = await host.realPath(path) } catch (error) { errors.push(`${archivePath}: ${isHostError(error, 'NotFound') ? 'a dangling symlink' : 'a symlink out of the payload'}`) continue } const inside = relative(realRoot, physical) if (inside === '..' || inside.startsWith(`..${host.path.sep}`) || isAbsolute(inside)) { errors.push(`${archivePath}: a symlink out of the payload`) continue } } const info = link.isSymlink ? await host.stat(physical) : link if (info.isDirectory) { tree.directories.add(archivePath) await walk(physical, archivePath) } else if (info.isFile) { tree.files.set(archivePath, { executable: ((info.mode ?? 0) & 0o111) !== 0 }) if (archivePath.startsWith('bin/') && info.size <= EXT_TOOLS_LAUNCHER_LIMIT) { tree.launchers.set(archivePath, await host.readFile(physical)) } } else { errors.push(`${archivePath}: not a regular file`) } } } await walk(realRoot, '') return { tree, errors } } /** `pikg doctor` of an extension package: the manifest against the App, every platform's payload, and, given a catalog * of the other packages, `requires` and same-named commands. */ async function extToolsChecks(app: AppMeta, pikg: PikgMeta, metaDir: string, catalogDir: string | undefined): Promise>> { const checks: Array> = [] const platforms = new Map() const stray: string[] = [] for (const [key, subpackage] of Object.entries(pikg.sub_pkgs)) { const platform = extToolsPlatformOfKey(key) if (!platform || subpackage.source.type !== 'path') { stray.push(key) continue } platforms.set(platform.name, resolve(metaDir, subpackage.source.path)) } const sources = [...platforms.values()] // /payload/: the package's manifest is two levels up const source = sources.length > 0 ? dirname(dirname(sources[0])) : dirname(metaDir) const master = await readExtToolsManifestFile(join(source, EXT_TOOLS_MANIFEST_FILE)) const manifestErrors = [...master.errors] if (stray.length > 0) manifestErrors.push(`sub packages must be ext_tools__ from a directory: ${stray.join(', ')}`) const manifest = master.manifest if (manifest) { if (manifest.id !== app.name) manifestErrors.push(`id ${manifest.id} is not the App name ${app.name}`) if (manifest.version !== app.version) manifestErrors.push(`version ${manifest.version} is not the App version ${app.version}`) const without = manifest.platforms.filter((name) => !platforms.has(name)) if (without.length > 0) manifestErrors.push(`platforms without a sub package: ${without.join(', ')}`) const unlisted = [...platforms.keys()].filter((name) => !manifest.platforms.includes(name)) if (unlisted.length > 0) manifestErrors.push(`sub packages of platforms it does not list: ${unlisted.join(', ')}`) } checks.push({ name: 'ext_tools_manifest', status: manifestErrors.length === 0 ? 'ok' : 'error', path: join(source, EXT_TOOLS_MANIFEST_FILE), ...(manifestErrors.length > 0 ? { errors: manifestErrors } : {}), }) if (!manifest) return checks for (const [platform, dir] of platforms) { const errors: string[] = [] try { const { tree, errors: walkErrors } = await readExtToolsPayloadTree(dir) errors.push(...walkErrors) const copy = await readExtToolsManifestFile(join(dir, EXT_TOOLS_MANIFEST_FILE)) if (copy.errors.length > 0) errors.push(`${EXT_TOOLS_MANIFEST_FILE}: ${copy.errors.join('; ')}`) else if (copy.text !== master.text) errors.push(`${EXT_TOOLS_MANIFEST_FILE}: differs from the package's manifest`) errors.push(...extToolsPayloadErrors(manifest, platform, tree, [source, metaDir])) } catch (error) { if (!isHostError(error, 'NotFound')) throw error errors.push(`${dir}: not found`) } checks.push({ name: 'ext_tools_payload', platform, status: errors.length === 0 ? 'ok' : 'error', path: dir, ...(errors.length > 0 ? { errors } : {}), }) } if (!catalogDir) { checks.push({ name: 'ext_tools_catalog', status: 'skipped', detail: 'no --catalog: requires and commands other packages also provide are not checked', }) return checks } const others = new Map() const catalogErrors: string[] = [] for (const entry of await getHost().readDir(catalogDir)) { if (entry.isFile) continue const candidate = await readExtToolsManifestFile(join(catalogDir, entry.name, EXT_TOOLS_MANIFEST_FILE)) if (candidate.errors.includes('not found')) continue if (!candidate.manifest) catalogErrors.push(`${entry.name}: ${candidate.errors.join('; ')}`) else if (candidate.manifest.id !== manifest.id) others.set(candidate.manifest.id, candidate.manifest) } for (const required of manifest.requires) { if (!others.has(required.id)) catalogErrors.push(`requires ${required.id}: not in the catalog`) } const commands = new Set(manifest.provides.map((provided) => provided.command)) for (const other of others.values()) { if (manifest.conflicts.includes(other.id) || other.conflicts.includes(manifest.id)) continue const shared = other.provides.map((provided) => provided.command).filter((command) => commands.has(command)) if (shared.length > 0) catalogErrors.push(`${other.id} also provides ${shared.join(', ')}: one of the two must list the other in conflicts`) } checks.push({ name: 'ext_tools_catalog', status: catalogErrors.length === 0 ? 'ok' : 'error', path: catalogDir, packages: [...others.keys()], ...(catalogErrors.length > 0 ? { errors: catalogErrors } : {}), }) return checks } async function buildCommand( ctx: CommandContext, input: Record, docker: DockerClient, now: () => number, ): Promise> { const metaInput = optionalInputString(input, 'meta_dir') ?? './dapp_meta' const metaDir = await realDirectory(resolveFromCwd(ctx, metaInput), 'dapp_meta') const appMeta = parseAppMeta(await readJson(join(metaDir, 'app.json'), 'app.json')) const pikgMeta = parsePikgMeta(await readJson(join(metaDir, 'pikg.json'), 'pikg.json'), appMeta) const configuredDist = resolve(metaDir, pikgMeta.output_dir) await rejectLeafSymlink(configuredDist, 'UNSAFE_OUTPUT_DIR') const distDir = await canonicalTarget(configuredDist) const projectDir = dirname(metaDir) const sourcePaths: string[] = [] for (const subpackage of Object.values(pikgMeta.sub_pkgs)) { if (subpackage.source.type === 'path') { sourcePaths.push(await getHost().realPath(resolve(metaDir, subpackage.source.path))) } } assertBuildPaths(metaDir, distDir, sourcePaths) await validateReplaceableDist(distDir, metaRootId(metaDir)) await getHost().mkdir(dirname(distDir), { recursive: true }) const temporary = await getHost().makeTempDir({ dir: dirname(distDir), prefix: '.buckyos-pikg-build-', }) try { const prepared: PreparedSubpackage[] = [] for ( const [key, subpackage] of Object.entries(pikgMeta.sub_pkgs).sort(([a], [b]) => a.localeCompare(b) ) ) { const payloadPath = join(temporary, `${key}.tar.gz`) let dockerInfo: DockerImageInfo | undefined if (subpackage.source.type === 'path') { const sourcePath = await getHost().realPath(resolve(metaDir, subpackage.source.path)) const info = await getHost().stat(sourcePath) if (info.isDirectory) { await createDeterministicTarGz(sourcePath, payloadPath) } else if (info.isFile && sourcePath.toLowerCase().endsWith('.tar.gz')) { const before = await digestFile(sourcePath) const beforeStat = statIdentity(await getHost().stat(sourcePath)) await getHost().copyFile(sourcePath, payloadPath) const after = await digestFile(sourcePath) const afterStat = statIdentity(await getHost().stat(sourcePath)) const copied = await digestFile(payloadPath) if ( beforeStat !== afterStat || before.size !== after.size || before.sha256 !== after.sha256 || copied.size !== before.size || copied.sha256 !== before.sha256 ) { throw new ToolError('SOURCE_CHANGED', `source changed while copied: ${key}`) } } else { throw new UsageError( 'INVALID_SOURCE', `${key} source must be a directory or .tar.gz file`, ) } } else { dockerInfo = await docker.inspect(subpackage.source.image) if (!SHA256_ID.test(dockerInfo.id)) { throw new ToolError( 'DOCKER_IDENTITY_INVALID', `Docker image ${key} has no immutable image ID`, ) } await docker.save(dockerInfo.id, payloadPath) const after = await docker.inspect(dockerInfo.id) if (after.id !== dockerInfo.id) { throw new ToolError( 'SOURCE_CHANGED', `Docker image identity changed while exporting: ${key}`, ) } } const digest = await digestFile(payloadPath) prepared.push({ key, input: subpackage, payloadPath, digest: { size: digest.size, digest: `sha256:${digest.sha256}` }, ...(dockerInfo ? { docker: dockerInfo } : {}), }) } const timestamp = now() if (!Number.isSafeInteger(timestamp) || timestamp < 0) throw new Error('invalid clock value') const namespace = deriveAppNamespace(appMeta.did) const packageObjects: Record> = {} const contentIndex: PackageMetaFile['content_index'] = {} const pkgList: Record> = {} const generatedSubpackages: DistManifest['subpackages'] = {} const packageNames = new Set() for (const item of prepared) { const packageName = `${packageEnvironmentQualifier(item.key, item.input.selector)}.${ packageSuffix(item.key) }.${namespace}` if (packageNames.has(packageName)) { throw new UsageError('PACKAGE_NAME_COLLISION', `subpackage names collide at ${packageName}`) } packageNames.add(packageName) const payloadHash = item.digest.digest.slice('sha256:'.length) const packageMeta = createPackageMeta( packageName, appMeta.version, appMeta.author, appMeta.owner, { size: item.digest.size, sha256: payloadHash, crc32: 0 }, timestamp, ) packageObjects[packageMeta.objectId] = packageMeta.value if (contentIndex[item.digest.digest]) { throw new UsageError( 'DUPLICATE_PAYLOAD_DIGEST', `subpackages cannot share the same payload digest: ${item.key}`, ) } contentIndex[item.digest.digest] = { sub_pkg_name: item.key, path: `${item.key}.tar.gz`, format: 'tar.gz', size: item.digest.size, digest: item.digest.digest, } const selector = item.input.selector pkgList[item.key] = { pkg_id: `${packageName}#${appMeta.version}`, pkg_objid: packageMeta.objectId, ...(item.docker ? { docker_image_name: item.docker.canonicalName, docker_image_digest: item.docker.id, } : {}), ...(selector ? { selector } : {}), required: item.input.required, } generatedSubpackages[item.key] = { source_kind: item.input.source.type, size: item.digest.size, digest: item.digest.digest, pkg_objid: packageMeta.objectId, } } const appDoc: Record = { schema_version: 1, doc_type: 'app', did: appMeta.did, name: appMeta.name, version: appMeta.version, app_type: appMeta.categories[0], author: appMeta.author, owner: appMeta.owner, controller: appMeta.owner, create_time: timestamp, last_update_time: timestamp, exp: timestamp + APP_DOCUMENT_LIFETIME_SECONDS, categories: appMeta.categories, pkg_list: pkgList, show_name: appMeta.show_name, ...(appMeta.presentation ? { presentation: appMeta.presentation } : {}), ...(appMeta.permissions.length ? { permissions: appMeta.permissions } : {}), ...(appMeta.content_handlers?.length ? { content_handlers: appMeta.content_handlers } : {}), selector_type: appMeta.selector_type, service_config_tips: appMeta.service_config_tips, } const appObjectId = appDocObjectId(appDoc) const packageMeta: PackageMetaFile = { '@schema': PACKAGE_META_SCHEMA, app_doc_id: appObjectId, package_objects: packageObjects, content_index: contentIndex, } await writeJson(join(temporary, APPDOC_ENTRY), appDoc) await writeJson(join(temporary, PACKAGE_META_ENTRY), packageMeta) const validated = await validateSnapshot(temporary, appDoc, packageMeta) const generatedFiles: DistManifest['generated_files'] = {} for ( const name of [ APPDOC_ENTRY, PACKAGE_META_ENTRY, ...prepared.map((item) => `${item.key}.tar.gz`), ] ) { const digest = await digestFile(join(temporary, name)) generatedFiles[name] = { size: digest.size, digest: `sha256:${digest.sha256}` } } const manifest: DistManifest = { schema_version: 1, tool_version: TOOL_VERSION, meta_root_id: metaRootId(metaDir), source_fingerprint: `sha256:${ stableJsonDigest({ app: appMeta, pikg: pikgMeta, payloads: generatedSubpackages, }) }`, app_doc_object_id: appObjectId, pikg_file: pikgMeta.pikg_file, generated_files: generatedFiles, subpackages: generatedSubpackages, } await writeJson(join(temporary, DIST_MANIFEST_NAME), manifest) await replaceDirectory(temporary, distDir) return { meta_dir: metaDir, dist_dir: distDir, app_did: appMeta.did, app_doc_object_id: appObjectId, subpackage_count: validated.subpackages.length, subpackages: validated.subpackages.map((item) => ({ key: item.key, source_kind: pikgMeta.sub_pkgs[item.key].source.type, size: item.payload_size, digest: item.payload_digest, pkg_objid: item.pkg_objid, })), ready_for_pack: true, next_command: `buckyos pikg pack ${distDir}`, project_dir: projectDir, } } catch (error) { await removeTreeIfExists(temporary) throw error } } async function packCommand( ctx: CommandContext, input: Record, ): Promise> { const distInput = optionalInputString(input, 'dist_dir') ?? './dapp_dist' const distDir = await safeExistingDirectory(resolveFromCwd(ctx, distInput), 'dapp_dist') const manifest = await validateManagedDist(distDir, undefined, true) const appDoc = await readJson(join(distDir, APPDOC_ENTRY), APPDOC_ENTRY) const packageMeta = parsePackageMeta( await readJson(join(distDir, PACKAGE_META_ENTRY), PACKAGE_META_ENTRY), ) const validated = await validateSnapshot(distDir, appDoc, packageMeta) if (validated.appDocObjectId !== manifest.app_doc_object_id) { throw new ToolError( 'INVALID_PACKAGE', 'snapshot AppDoc Object ID differs from ownership manifest', ) } const temporary = join(distDir, `.${manifest.pikg_file}.tmp-${crypto.randomUUID()}`) const finalPath = join(distDir, manifest.pikg_file) try { await packSnapshot(distDir, temporary, appDoc, packageMeta) const inspection = await inspectPikg(temporary) if (inspection.app.app_doc_object_id !== manifest.app_doc_object_id) { throw new ToolError( 'INVALID_PACKAGE', 'PIKG self-check returned a different AppDoc Object ID', ) } await replaceFile(temporary, finalPath) const digest = await digestFile(finalPath) return { dist_dir: distDir, pikg_path: finalPath, size: digest.size, pikg_digest: `sha256:${digest.sha256}`, app_doc_object_id: inspection.app.app_doc_object_id, validation: 'passed', } } catch (error) { await removeFileIfExists(temporary) throw error } } async function cleanCommand( ctx: CommandContext, input: Record, ): Promise> { const metaInput = optionalInputString(input, 'meta_dir') ?? './dapp_meta' const metaDir = await realDirectory(resolveFromCwd(ctx, metaInput), 'dapp_meta') const appMeta = parseAppMeta(await readJson(join(metaDir, 'app.json'), 'app.json')) const pikgMeta = parsePikgMeta( await readJson(join(metaDir, 'pikg.json'), 'pikg.json'), appMeta, ) const configuredDist = resolve(metaDir, pikgMeta.output_dir) assertSafeCleanTarget(ctx, metaDir, configuredDist, []) await rejectLeafSymlink(configuredDist, 'UNSAFE_CLEAN_TARGET') const distDir = await canonicalTarget(configuredDist) try { await getHost().lstat(distDir) } catch (error) { if (isHostError(error, 'NotFound')) { return { meta_dir: metaDir, dist_dir: distDir, removed: false } } throw error } const sourcePaths: string[] = [] for (const subpackage of Object.values(pikgMeta.sub_pkgs)) { if (subpackage.source.type === 'path') { try { sourcePaths.push(await getHost().realPath(resolve(metaDir, subpackage.source.path))) } catch (error) { if (!isHostError(error, 'NotFound')) throw error } } } assertSafeCleanTarget(ctx, metaDir, distDir, sourcePaths) await validateManagedDist(distDir, metaRootId(metaDir), true, 'UNSAFE_CLEAN_TARGET') if (!ctx.confirmed) { if (ctx.config.nonInteractive || ctx.interactive || !ctx.io.inputIsTerminal) { throw new ToolError( 'CONFIRMATION_REQUIRED', 'pikg clean requires --yes in non-interactive mode', EXIT_PERMISSION, ) } const answer = await ctx.io.prompt(`Delete managed PIKG output ${distDir}? [y/N] `) if (!answer || !['y', 'yes'].includes(answer.trim().toLowerCase())) { throw new ToolError('CONFIRMATION_DECLINED', 'PIKG clean was declined', EXIT_PERMISSION) } } await getHost().remove(distDir, { recursive: true }) return { meta_dir: metaDir, dist_dir: distDir, removed: true } } function parseAppMeta(value: Record): AppMeta { rejectUnknown( value, [ 'schema_version', 'did', 'name', 'version', 'owner', 'author', 'show_name', 'presentation', 'categories', 'permissions', 'content_handlers', 'selector_type', 'service_config_tips', ], 'app.json', ) if (value.schema_version !== 1) { throw new UsageError('UNSUPPORTED_SCHEMA_VERSION', 'app.json.schema_version must be 1') } const name = developmentString(value.name, 'app.json.name') validateAppName(name) const version = developmentString(value.version, 'app.json.version') validateVersion(version) const did = developmentString(value.did, 'app.json.did') const owner = developmentString(value.owner, 'app.json.owner') deriveAppNamespace(did) const categories = value.categories if ( !Array.isArray(categories) || !categories.length || categories.some((item) => typeof item !== 'string') ) { throw new UsageError( 'SCHEMA_VALIDATION_FAILED', 'app.json.categories must be a non-empty string array', ) } const permissions = developmentValidation( () => validatePermissions(value.permissions ?? [], 'app.json.permissions'), ) const serviceConfig = developmentValidation(() => validateServiceConfigTips( value.service_config_tips ?? {}, 'app.json.service_config_tips', ) ) return { schema_version: 1, did, name, version, owner, author: developmentString(value.author, 'app.json.author'), show_name: developmentString(value.show_name, 'app.json.show_name'), ...(value.presentation === undefined ? {} : { presentation: developmentValidation(() => validateAppPresentation(value.presentation, 'app.json.presentation') ), }), categories: categories as string[], permissions, ...(value.content_handlers === undefined ? {} : { content_handlers: developmentValidation(() => validateContentHandlers(value.content_handlers, permissions)) }), selector_type: developmentString(value.selector_type, 'app.json.selector_type'), service_config_tips: serviceConfig, } } function parsePikgMeta(value: Record, app?: AppMeta): PikgMeta { rejectUnknown(value, ['schema_version', 'output_dir', 'pikg_file', 'sub_pkgs'], 'pikg.json') if (value.schema_version !== 1) { throw new UsageError('UNSUPPORTED_SCHEMA_VERSION', 'pikg.json.schema_version must be 1') } const outputDir = value.output_dir === undefined ? '../dapp_dist' : developmentString(value.output_dir, 'pikg.json.output_dir') const defaultPikgFile = app ? `${app.name}-${app.version}.pikg` : undefined const pikgFile = value.pikg_file === undefined ? defaultPikgFile ?? (() => { throw new UsageError('SCHEMA_VALIDATION_FAILED', 'pikg.json.pikg_file is required') })() : developmentString(value.pikg_file, 'pikg.json.pikg_file') if ( !SAFE_PIKG_FILE.test(pikgFile) || pikgFile.includes('..') || basename(pikgFile) !== pikgFile ) { throw new UsageError('INVALID_PIKG_FILE', 'pikg_file must be a safe .pikg file name') } const rawSubpackages = developmentObject(value.sub_pkgs, 'pikg.json.sub_pkgs') if (!Object.keys(rawSubpackages).length) { throw new UsageError('SCHEMA_VALIDATION_FAILED', 'pikg.json.sub_pkgs must not be empty') } const subpackages: Record = {} for (const [key, raw] of Object.entries(rawSubpackages)) { validateSubpackageName(key) const subpackage = developmentObject(raw, `pikg.json.sub_pkgs.${key}`) rejectUnknown(subpackage, ['selector', 'required', 'source'], `pikg.json.sub_pkgs.${key}`) const selector = developmentValidation(() => canonicalSelector(subpackage.selector, `pikg.json.sub_pkgs.${key}.selector`) ) assertSelectorCompatible(key, selector, `pikg.json.sub_pkgs.${key}.selector`) if (subpackage.required !== undefined && typeof subpackage.required !== 'boolean') { throw new UsageError('SCHEMA_VALIDATION_FAILED', `${key}.required must be boolean`) } const source = developmentObject(subpackage.source, `pikg.json.sub_pkgs.${key}.source`) if (source.type === 'path') { rejectUnknown(source, ['type', 'path'], `pikg.json.sub_pkgs.${key}.source`) subpackages[key] = { ...(selector ? { selector } : {}), required: subpackage.required === undefined ? true : subpackage.required, source: { type: 'path', path: developmentString(source.path, `${key}.source.path`) }, } } else if (source.type === 'docker-image') { rejectUnknown(source, ['type', 'image'], `pikg.json.sub_pkgs.${key}.source`) subpackages[key] = { ...(selector ? { selector } : {}), required: subpackage.required === undefined ? true : subpackage.required, source: { type: 'docker-image', image: developmentString(source.image, `${key}.source.image`), }, } } else { throw new UsageError('INVALID_SOURCE', `${key}.source.type must be path or docker-image`) } } return { schema_version: 1, output_dir: outputDir, pikg_file: pikgFile, sub_pkgs: subpackages, } } async function initializeMetaDirectory( projectDir: string, metaDir: string, appMeta: AppMeta, pikgMeta: Record, ): Promise { let existedEmpty = false try { const stat = await getHost().lstat(metaDir) if (!stat.isDirectory || stat.isSymlink) { throw new UsageError( 'ALREADY_EXISTS', 'dapp_meta already exists and is not an empty directory', ) } for (const _entry of await getHost().readDir(metaDir)) { throw new UsageError('ALREADY_EXISTS', 'dapp_meta already contains files') } existedEmpty = true } catch (error) { if (!isHostError(error, 'NotFound')) throw error } const temporary = await getHost().makeTempDir({ dir: projectDir, prefix: '.buckyos-pikg-init-' }) try { await writeJson(join(temporary, 'app.json'), appMeta) await writeJson(join(temporary, 'pikg.json'), pikgMeta) parseAppMeta(await readJson(join(temporary, 'app.json'), 'app.json')) parsePikgMeta(await readJson(join(temporary, 'pikg.json'), 'pikg.json'), appMeta) if (existedEmpty) await getHost().remove(metaDir) try { await getHost().rename(temporary, metaDir) } catch (error) { if (existedEmpty) await getHost().mkdir(metaDir) throw error } } catch (error) { await removeTreeIfExists(temporary) throw error } } async function validateReplaceableDist(distDir: string, expectedMetaRootId: string): Promise { try { await getHost().lstat(distDir) } catch (error) { if (isHostError(error, 'NotFound')) return throw error } await validateManagedDist(distDir, expectedMetaRootId, true) } async function validateManagedDist( distDir: string, expectedMetaRootId?: string, verifyFiles = true, unsafeCode = 'UNSAFE_DIST_TARGET', ): Promise { try { const info = await getHost().lstat(distDir) if (!info.isDirectory || info.isSymlink) throw new Error('target is not a real directory') const manifest = parseDistManifest( await readJson(join(distDir, DIST_MANIFEST_NAME), DIST_MANIFEST_NAME), ) if (expectedMetaRootId && manifest.meta_root_id !== expectedMetaRootId) { throw new Error('ownership manifest belongs to another dapp_meta') } const allowed = new Set([ DIST_MANIFEST_NAME, manifest.pikg_file, ...Object.keys(manifest.generated_files), ]) for (const entry of await getHost().readDir(distDir)) { if (!entry.isFile || entry.isSymlink || !allowed.has(entry.name)) { throw new Error(`unmanaged entry exists: ${entry.name}`) } } for (const name of Object.keys(manifest.generated_files)) { const info = await getHost().lstat(join(distDir, name)) if (!info.isFile || info.isSymlink) throw new Error(`generated file is unsafe: ${name}`) if (verifyFiles) { const expected = manifest.generated_files[name] const actual = await digestFile(join(distDir, name)) if (actual.size !== expected.size || `sha256:${actual.sha256}` !== expected.digest) { throw new Error(`generated file was modified: ${name}`) } } } return manifest } catch (error) { if (error instanceof ToolError && error.code === unsafeCode) throw error throw new ToolError( unsafeCode, `managed dist validation failed: ${error instanceof Error ? error.message : String(error)}`, 6, ) } } function parseDistManifest(value: Record): DistManifest { rejectUnknown( value, [ 'schema_version', 'tool_version', 'meta_root_id', 'source_fingerprint', 'app_doc_object_id', 'pikg_file', 'generated_files', 'subpackages', ], DIST_MANIFEST_NAME, ) if (value.schema_version !== 1) throw new Error('unsupported ownership manifest version') const pikgFile = String(value.pikg_file ?? '') if ( !SAFE_PIKG_FILE.test(pikgFile) || pikgFile.includes('..') || basename(pikgFile) !== pikgFile ) { throw new Error('ownership manifest has an unsafe pikg_file') } const generatedRaw = expectObject(value.generated_files, `${DIST_MANIFEST_NAME}.generated_files`) const generated: Record = {} for (const [name, raw] of Object.entries(generatedRaw)) { if ( !SAFE_GENERATED_FILE.test(name) || name === '.' || name === '..' || name.includes('\\') || basename(name) !== name || name === DIST_MANIFEST_NAME || name === pikgFile ) { throw new Error(`ownership manifest has an unsafe generated file: ${name}`) } const record = expectObject(raw, `generated_files.${name}`) rejectUnknown(record, ['size', 'digest'], `generated_files.${name}`) if (typeof record.size !== 'number' || !Number.isSafeInteger(record.size) || record.size < 0) { throw new Error(`generated_files.${name}.size is invalid`) } if (typeof record.digest !== 'string' || !SHA256_ID.test(record.digest)) { throw new Error(`generated_files.${name}.digest is invalid`) } generated[name] = { size: record.size, digest: record.digest } } if (!generated[APPDOC_ENTRY] || !generated[PACKAGE_META_ENTRY]) { throw new Error('ownership manifest is missing required metadata files') } return { schema_version: 1, tool_version: String(value.tool_version ?? ''), meta_root_id: validateDigestString(value.meta_root_id, 'meta_root_id'), source_fingerprint: validateDigestString(value.source_fingerprint, 'source_fingerprint'), app_doc_object_id: validateObjectId(value.app_doc_object_id, 'app_doc_object_id'), pikg_file: pikgFile, generated_files: generated, subpackages: expectObject(value.subpackages, 'subpackages') as DistManifest['subpackages'], } } function assertBuildPaths(metaDir: string, distDir: string, sourcePaths: string[]): void { if (pathsOverlap(metaDir, distDir)) { throw new UsageError('UNSAFE_OUTPUT_DIR', 'output_dir overlaps dapp_meta') } for (const source of sourcePaths) { if (pathsOverlap(source, distDir)) { throw new UsageError('UNSAFE_OUTPUT_DIR', 'output_dir overlaps a subpackage source') } } } function assertSafeCleanTarget( ctx: CommandContext, metaDir: string, distDir: string, sourcePaths: string[], ): void { const projectDir = dirname(metaDir) const exactProtected = [resolve(ctx.cwd), projectDir] const home = getHost().env('HOME') ?? getHost().env('USERPROFILE') if (home) exactProtected.push(resolve(home)) if ( dirname(distDir) === distDir || exactProtected.some((path) => resolve(path) === resolve(distDir)) || pathsOverlap(metaDir, distDir) || sourcePaths.some((path) => pathsOverlap(path, distDir)) ) { throw new ToolError('UNSAFE_CLEAN_TARGET', 'refusing to clean an unsafe output directory') } } async function replaceDirectory(temporary: string, destination: string): Promise { let exists = false try { await getHost().lstat(destination) exists = true } catch (error) { if (!isHostError(error, 'NotFound')) throw error } if (!exists) { await getHost().rename(temporary, destination) return } const backup = `${destination}.previous-${crypto.randomUUID()}` await getHost().rename(destination, backup) try { await getHost().rename(temporary, destination) } catch (error) { await getHost().rename(backup, destination) throw error } await getHost().remove(backup, { recursive: true }) } async function replaceFile(temporary: string, destination: string): Promise { let exists = false try { await getHost().lstat(destination) exists = true } catch (error) { if (!isHostError(error, 'NotFound')) throw error } if (!exists) { await getHost().rename(temporary, destination) return } const backup = `${destination}.previous-${crypto.randomUUID()}` await getHost().rename(destination, backup) try { await getHost().rename(temporary, destination) } catch (error) { await getHost().rename(backup, destination) throw error } await removeFileIfExists(backup) } class LocalDockerClient implements DockerClient { async inspect(reference: string): Promise { let result try { result = await getHost().run('docker', ['image', 'inspect', reference]) } catch (error) { throw new ToolError( 'DOCKER_UNAVAILABLE', `Docker inspect is unavailable: ${error instanceof Error ? error.message : String(error)}`, EXIT_UNAVAILABLE, true, ) } if (!result.success) { throw new ToolError( 'DOCKER_IMAGE_NOT_FOUND', `local Docker image is unavailable: ${safeDockerError(result.stderr)}`, EXIT_UNAVAILABLE, ) } let values: unknown try { values = JSON.parse(new TextDecoder().decode(result.stdout)) } catch { throw new ToolError('DOCKER_INSPECT_INVALID', 'Docker inspect returned invalid JSON') } if (!Array.isArray(values) || values.length !== 1) { throw new ToolError('DOCKER_INSPECT_INVALID', 'Docker inspect returned an unexpected result') } const value = developmentObject(values[0], 'Docker inspect') const id = developmentString(value.Id, 'Docker image ID').toLowerCase() if (!SHA256_ID.test(id)) { throw new ToolError('DOCKER_IDENTITY_INVALID', 'Docker image ID is not immutable sha256') } const architecture = developmentString(value.Architecture, 'Docker architecture') const tags = Array.isArray(value.RepoTags) ? value.RepoTags.filter((tag): tag is string => typeof tag === 'string' && tag !== ':' ) : [] return { id, architecture, canonicalName: tags.includes(reference) ? reference : tags[0] ?? reference, } } async save(imageId: string, destinationTarGz: string): Promise { try { const result = await getHost().runGzip( 'docker', ['image', 'save', imageId], destinationTarGz, ) if (!result.success) { await removeFileIfExists(destinationTarGz) throw new ToolError( 'DOCKER_EXPORT_FAILED', `Docker image save failed: ${safeDockerError(result.stderr)}`, EXIT_UNAVAILABLE, ) } } catch (error) { if (error instanceof ToolError) throw error throw new ToolError( 'DOCKER_UNAVAILABLE', `Docker save is unavailable: ${error instanceof Error ? error.message : String(error)}`, EXIT_UNAVAILABLE, true, ) } } } function resolveFromCwd(ctx: CommandContext, value: string): string { return isAbsolute(value) ? resolve(value) : resolve(ctx.cwd, value) } async function realDirectory(path: string, label: string): Promise { const real = await getHost().realPath(path) const stat = await getHost().stat(real) if (!stat.isDirectory) throw new UsageError('INVALID_PATH', `${label} must be a directory`) return real } async function safeExistingDirectory(path: string, label: string): Promise { const info = await getHost().lstat(path) if (!info.isDirectory || info.isSymlink) { throw new UsageError('INVALID_PATH', `${label} must be a real directory`) } return await getHost().realPath(path) } async function canonicalTarget(path: string): Promise { const absolute = resolve(path) try { return await getHost().realPath(absolute) } catch (error) { if (!isHostError(error, 'NotFound')) throw error const parent = dirname(absolute) if (parent === absolute) return absolute return join(await canonicalTarget(parent), basename(absolute)) } } async function rejectLeafSymlink(path: string, code: string): Promise { try { if ((await getHost().lstat(path)).isSymlink) { throw new ToolError(code, 'configured output_dir must not be a symlink') } } catch (error) { if (isHostError(error, 'NotFound')) return throw error } } function pathsOverlap(left: string, right: string): boolean { const leftToRight = relative(resolve(left), resolve(right)) const rightToLeft = relative(resolve(right), resolve(left)) const separator = getHost().path.sep return leftToRight === '' || !leftToRight.startsWith(`..${separator}`) && leftToRight !== '..' || !rightToLeft.startsWith(`..${separator}`) && rightToLeft !== '..' } function metaRootId(metaDir: string): string { return `sha256:${sha256Bytes(new TextEncoder().encode(resolve(metaDir)))}` } function packageSuffix(key: string): string { const suffix = key.toLowerCase().replaceAll(/[^a-z0-9_-]+/g, '-').replaceAll(/^-+|-+$/g, '') if (!suffix) { throw new UsageError('INVALID_SUBPACKAGE_NAME', `cannot derive package name from ${key}`) } return suffix } function normalizeAppName(value: string): string { return value.toLowerCase().replaceAll(/[^a-z0-9]+/g, '-').replaceAll(/^-+|-+$/g, '') } function validateAppName(value: string): void { if (!APP_NAME.test(value)) throw new UsageError('INVALID_APP_NAME', `invalid App name: ${value}`) } function validateVersion(value: string): void { if (!VERSION.test(value)) throw new UsageError('INVALID_VERSION', `invalid App version: ${value}`) } function deriveAppDid(name: string, owner: string): string { const match = /^did:bns:([a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$/.exec(owner) if (!match) { throw new UsageError( 'INVALID_OWNER_DID', 'Owner DID must be a standard single-label did:bns DID for an ordinary App', ) } return `did:bns:${name}.${match[1]}` } async function requiredPrompt( ctx: CommandContext, canPrompt: boolean, message: string, field: string, ): Promise { if (!canPrompt) { throw new UsageError('MISSING_REQUIRED_INPUT', `${field} is required`) } const answer = await ctx.io.prompt(message) if (!answer?.trim()) throw new UsageError('MISSING_REQUIRED_INPUT', `${field} is required`) return answer.trim() } function optionalInputString(input: Record, key: string): string | undefined { return input[key] === undefined ? undefined : expectInputString(input, key) } function expectInputString(input: Record, key: string): string { const value = input[key] if (typeof value !== 'string' || !value) { throw new UsageError('MISSING_REQUIRED_INPUT', `${key} is required`) } return value } function developmentString(value: unknown, label: string): string { try { return expectNonEmptyString(value, label) } catch (error) { if (error instanceof ToolError) throw new UsageError('SCHEMA_VALIDATION_FAILED', error.message) throw error } } function developmentObject(value: unknown, label: string): Record { try { return expectObject(value, label) } catch (error) { if (error instanceof ToolError) throw new UsageError('SCHEMA_VALIDATION_FAILED', error.message) throw error } } function developmentValidation(validate: () => T): T { try { return validate() } catch (error) { if (error instanceof ToolError) throw new UsageError('SCHEMA_VALIDATION_FAILED', error.message) throw error } } async function readJson(path: string, label: string): Promise> { try { const parsed = JSON.parse(await getHost().readTextFile(path)) return developmentObject(parsed, label) } catch (error) { if (error instanceof SyntaxError) { throw new UsageError('INVALID_JSON', `${label} is not valid JSON`) } throw error } } async function writeJson(path: string, value: unknown): Promise { await getHost().writeTextFile(path, `${JSON.stringify(value, null, 2)}\n`, { createNew: true, mode: 0o600, }) } function validateDigestString(value: unknown, label: string): string { if (typeof value !== 'string' || !SHA256_ID.test(value)) throw new Error(`${label} is invalid`) return value } function validateObjectId(value: unknown, label: string): string { if (typeof value !== 'string' || !OBJECT_ID.test(value)) throw new Error(`${label} is invalid`) return value } function statIdentity(value: HostFileInfo): string { return JSON.stringify({ size: value.size, mtime: value.mtime?.getTime() ?? null, dev: value.dev, ino: value.ino, mode: value.mode, }) } function displaySource(projectDir: string, source: string): string { const display = relative(projectDir, source) return display && !display.startsWith(`..${getHost().path.sep}`) && display !== '..' ? toPortablePath(display) : '[external path]' } function toPortablePath(path: string): string { return path.split(getHost().path.sep).join('/') || '.' } function safeDockerError(bytes: Uint8Array): string { const text = new TextDecoder().decode(bytes).trim().replaceAll(/[\r\n]+/g, ' ') return text.slice(0, 500) || 'unknown Docker error' } async function removeTreeIfExists(path: string): Promise { try { await getHost().remove(path, { recursive: true }) } catch (error) { if (!isHostError(error, 'NotFound')) throw error } } async function removeFileIfExists(path: string): Promise { try { await getHost().remove(path) } catch (error) { if (!isHostError(error, 'NotFound')) throw error } }