@kruntime/kimage

@kruntime/kimage owns K image authoring.

The root entrypoint is cross-platform and provides helpers for writing plain runtime image objects that @kruntime/komputer can boot.

It owns:

• image()
• agent()
• defineCommand()
• command()
• hook()
• cron()
• login()
• model, secret, and mount needs helpers
• arg descriptors for JSON-safe command argument metadata

Example:

import { arg, command, hook, model, mount, secret } from '@kruntime/kimage'

export default command({
  help: `
Usage: list-target [--target PATH]

List a K filesystem target.
`,
  args: {
    target: arg.path().default('/workspace').describe('K path to list.'),
  },
  readonly: true,
  parallelSafe: true,
  timeout: '10s',
  async main(ctx) {
    const result = await ctx.exec({
      command: 'ls',
      argv: [String(ctx.args.target)],
    })
    return ctx.text(result.stdout || '')
  },
})

login() is just a typing helper for home/<agent>/.k/login.ts; the loader also accepts a plain default function.

Node-only source directory loading lives in:

import { buildImageFromDir, loadImageFromDir } from '@kruntime/kimage/node'

That subpath owns:

• active file discovery
• .cmd.ts/.cmd.sh/.cmd.md
• .hook.ts/.hook.sh/.hook.md
• .cron.ts/.cron.sh/.cron.md
• expanded active files such as bin/ticket/note/cmd.ts, etc/k/hooks/cmd.before/rm/hook.ts, and home/assistant/.k/cron/dream/cron.md
• .kimage/manifest.json build output
• content-addressed image blobs

Directory-loaded images get a stable content-based sha256:... digest unless the image config explicitly provides one. .kimage/ is ignored by digesting, so building the package does not change the source identity. tests/ is also ignored by image digests and packages; image tests validate the computer but are not part of the computer image itself. Local secret files such as .env, .env.local, .npmrc, and .secrets/ are also excluded; secrets are runtime bindings, not image bytes. .env.example may be packaged as documentation.

For active files, the path is the source of truth:

• bin/ticket/note.cmd.ts registers ticket.note
• bin/ticket/note/cmd.ts also registers ticket.note
• etc/k/hooks/cmd.before/rm.hook.ts registers cmd.before
• etc/k/hooks/cmd.before/rm/hook.ts also registers cmd.before
• home/assistant/.k/cron/dream.cron.ts registers dream
• home/assistant/.k/cron/dream/cron.ts also registers dream

If a module or markdown frontmatter declares a conflicting name or event, loading fails during build/test. This keeps image packages reproducible and prevents hidden command or hook aliases.

Shell active files can declare the same small metadata surface through leading comments:

# k: help Usage: test [ARG...]
# k: args argv
# k: readonly false
# k: parallelSafe false
# k: timeout 2m

K commands use one Unix executable contract everywhere: help, args, readonly, parallelSafe, timeout, and main(ctx). See developer-docs/reference/commands.md for the full standard.

It does not own runtime execution, sessions, authority, storage, or CLI UX.