orizu 0.5.19 → 0.5.21

package/src/instruction-set-manifest.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
+
+export interface InstructionSetComponent { key: string; modelConfig?: string; text: string }
+export interface InstructionSetManifest { name: string; description?: string | null; shape: string[]; components: InstructionSetComponent[] }
+
+// Keep file-backed component reads within the same text budget used by prompt
+// tooling; request assembly never asks Node to allocate an unbounded body.
+export const MAX_INSTRUCTION_SET_COMPONENT_BYTES = 512 * 1024
+
+const fail = (code: string): never => { throw new Error(code) }
+const sha256 = (value: string) => createHash('sha256').update(value, 'utf8').digest('hex')
+
+function hasPinnedComponents(material: unknown): boolean {
+  if (!material || typeof material !== 'object') return false
+  const pinned = (material as Record<string, unknown>).pinnedComponents
+  return Boolean(pinned && typeof pinned === 'object' && Object.keys(pinned).length > 0)
+}
+
+export function loadInstructionSetManifest(path: string): InstructionSetManifest {
+  let value: unknown
+  let source: string
+  try { source = readFileSync(path, 'utf8') } catch { return fail('instruction_set_path_not_found') }
+  try { value = JSON.parse(source) } catch { return fail('instruction_set_manifest_invalid_json') }
+  if (!value || typeof value !== 'object') return fail('instruction_set_manifest_invalid')
+  const input = value as Record<string, unknown>
+  if (typeof input.name !== 'string' || input.name.trim() === '') return fail('instruction_set_manifest_invalid_name')
+  const hasDescription = Object.hasOwn(input, 'description')
+  if (hasDescription && input.description !== null && typeof input.description !== 'string') return fail('instruction_set_manifest_invalid_description')
+  const description = hasDescription
+    ? input.description === '' ? null : input.description as string | null
+    : undefined
+  if (hasPinnedComponents(input.default)) return fail('instruction_set_component_unavailable')
+  if (!Array.isArray(input.shape) || input.shape.length === 0 || input.shape.some(key => typeof key !== 'string' || key === '') || new Set(input.shape).size !== input.shape.length) return fail('instruction_set_manifest_invalid_shape')
+  if (!Array.isArray(input.components)) return fail('instruction_set_manifest_invalid_components')
+  let root: string
+  try { root = realpathSync(dirname(path)) } catch { return fail('instruction_set_path_not_found') }
+  const seen = new Set<string>()
+  const loadedComponents: Array<InstructionSetComponent & { changedSinceSync: boolean; hasSyncBaseline: boolean }> = []
+  for (const raw of input.components) {
+    if (!raw || typeof raw !== 'object') return fail('instruction_set_manifest_invalid_component')
+    const component = raw as Record<string, unknown>
+    if (typeof component.key !== 'string' || component.key === '' || !input.shape.includes(component.key)) return fail(component.key && !input.shape.includes(component.key) ? 'instruction_set_key_outside_shape' : 'instruction_set_manifest_invalid_component')
+    const modelConfig = component.modelConfig === undefined ? undefined : component.modelConfig
+    if (modelConfig !== undefined && (typeof modelConfig !== 'string' || modelConfig === '')) return fail('instruction_set_manifest_invalid_component')
+    const identity = `${component.key}\u0000${modelConfig ?? ''}`; if (seen.has(identity)) return fail('instruction_set_duplicate_component'); seen.add(identity)
+    let text: string
+    if (typeof component.text === 'string' && component.path === undefined) text = component.text
+    else if (typeof component.path === 'string' && component.text === undefined) {
+      if (isAbsolute(component.path)) return fail('instruction_set_path_escape')
+      const candidate = resolve(root, component.path)
+      if (relative(root, candidate).startsWith('..')) return fail('instruction_set_path_escape')
+      if (!existsSync(candidate)) return fail('instruction_set_path_not_found')
+      let target: string; try { target = realpathSync(candidate) } catch { return fail('instruction_set_path_not_found') }
+      if (relative(root, target).startsWith('..')) return fail('instruction_set_path_escape')
+      try { text = readFileSync(target, 'utf8') } catch { return fail('instruction_set_path_not_found') }
+      if (Buffer.byteLength(text, 'utf8') > MAX_INSTRUCTION_SET_COMPONENT_BYTES) return fail('instruction_set_component_too_large')
+    } else return fail('instruction_set_manifest_invalid_component')
+    if (Buffer.byteLength(text, 'utf8') > MAX_INSTRUCTION_SET_COMPONENT_BYTES) return fail('instruction_set_component_too_large')
+    const hasSyncBaseline = typeof component.syncedContentSha256 === 'string'
+    if (component.syncedContentSha256 !== undefined && (!hasSyncBaseline || !/^[a-f0-9]{64}$/u.test(component.syncedContentSha256 as string))) return fail('instruction_set_manifest_invalid_component')
+    loadedComponents.push({
+      key: component.key,
+      ...(modelConfig === undefined ? {} : { modelConfig }),
+      text,
+      hasSyncBaseline,
+      changedSinceSync: hasSyncBaseline && sha256(text) !== component.syncedContentSha256,
+    })
+  }
+  for (const key of input.shape) if (!loadedComponents.some(component => component.key === key)) return fail('instruction_set_missing_shape_key')
+  const defaultIdentity = input.default && typeof input.default === 'object'
+    && typeof (input.default as Record<string, unknown>).modelConfigIdentity === 'string'
+    ? (input.default as Record<string, unknown>).modelConfigIdentity as string
+    : null
+  let components = loadedComponents
+  if (defaultIdentity) {
+    if (input.manifestVersion === 1 && (input.shape as string[]).some(key => {
+      const bare = loadedComponents.find(component => component.key === key && component.modelConfig === undefined)
+      const tagged = loadedComponents.find(component => component.key === key && component.modelConfig === defaultIdentity)
+      return bare && tagged && (!bare.hasSyncBaseline || !tagged.hasSyncBaseline)
+    })) return fail('instruction_set_sync_baseline_missing')
+    const changedDefaultKeys = new Set(loadedComponents.flatMap(component => (
+      component.modelConfig === undefined && component.hasSyncBaseline && component.changedSinceSync
+        ? [component.key]
+        : []
+    )))
+    const changedSameIdentityKeys = new Set(loadedComponents.flatMap(component => (
+      component.modelConfig === defaultIdentity && component.hasSyncBaseline && component.changedSinceSync
+        ? [component.key]
+        : []
+    )))
+    if ([...changedDefaultKeys].some(key => changedSameIdentityKeys.has(key))) return fail('instruction_set_conflicting_synced_edits')
+    if (changedDefaultKeys.size > 0) {
+      components = loadedComponents.filter(component => (
+        component.modelConfig !== defaultIdentity || !changedDefaultKeys.has(component.key)
+      ))
+    }
+  }
+  const namedProfiles = new Set([
+    ...(components.some(component => component.modelConfig === undefined) && defaultIdentity
+      ? [defaultIdentity]
+      : []),
+    ...components.flatMap(component => component.modelConfig ? [component.modelConfig] : []),
+  ])
+  const namedProfileHasPins = Array.isArray(input.profiles) && input.profiles.some(profile => {
+    if (!profile || typeof profile !== 'object') return false
+    const value = profile as Record<string, unknown>
+    return typeof value.modelConfigIdentity === 'string'
+      && namedProfiles.has(value.modelConfigIdentity)
+      && hasPinnedComponents(value.production)
+  })
+  if (namedProfileHasPins) return fail('instruction_set_component_unavailable')
+  return {
+    name: input.name,
+    ...(hasDescription ? { description } : {}),
+    shape: input.shape as string[],
+    components: components.map(({ key, modelConfig, text }) => ({ key, ...(modelConfig === undefined ? {} : { modelConfig }), text })),
+  }
+}

package/src/instruction-sets-cli.ts

@@ -0,0 +1,306 @@
+import { authedFetch } from './http.js'
+import { loadInstructionSetManifest, MAX_INSTRUCTION_SET_COMPONENT_BYTES, type InstructionSetManifest } from './instruction-set-manifest.js'
+import { sanitizeHumanInlineText, sanitizeTerminalText } from './json-response.js'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+
+export interface InstructionSetsCommandIo {
+  json: boolean
+  print: (line: string) => void
+  resolveProjectSlug: (provided: string | null) => Promise<string>
+}
+
+function positionalArgs(args: string[]): string[] {
+  const values: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index]!
+    if (value.startsWith('--')) {
+      if (argValue(args, value) !== null) index += 1
+      continue
+    }
+    values.push(value)
+  }
+  return values
+}
+
+function argValue(args: string[], flag: string): string | null {
+  const index = args.indexOf(flag)
+  return index === -1 || !args[index + 1] || args[index + 1]!.startsWith('--')
+    ? null
+    : args[index + 1]!
+}
+
+async function responsePayload(response: Response, action: string): Promise<Record<string, unknown>> {
+  const payload = await response.json().catch(() => ({})) as Record<string, unknown>
+  if (!response.ok) {
+    throw new Error(`${action} failed (${response.status}): ${typeof payload.error === 'string' ? payload.error : response.statusText}`)
+  }
+  return payload
+}
+
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/u
+export interface SyncComponent { body?: string; repoPath?: string; contentSha?: string; commitSha?: string }
+export interface SyncMaterial { profileVersionId: string; versionNumber: number; modelConfigIdentity: string; resolvedFrom: string; components: Record<string, SyncComponent> }
+export interface SyncProfile { modelConfigIdentity: string; resolvedFrom: string; production: SyncMaterial | null }
+export interface SyncSet { name: string; slug?: string; description?: string | null; shape: string[]; default: SyncMaterial; profiles: SyncProfile[]; filteredTo?: string[] }
+function safeSegment(value: string) { if (!SAFE_SEGMENT.test(value) || value === '.' || value === '..' || value.startsWith('.')) throw new Error('instruction_set_path_unsafe') }
+function slug(identity: string) { return identity.replaceAll('/', '__').replace(/[^A-Za-z0-9._-]/gu, '_') }
+function stable(value: unknown): string { return `${JSON.stringify(value, null, 2)}\n` }
+function sha256(value: string): string { return createHash('sha256').update(value, 'utf8').digest('hex') }
+
+export interface SyncFileOps { writeFileSync: typeof writeFileSync; renameSync?: typeof renameSync }
+
+function writeMaterial(root: string, material: SyncMaterial, shape: string[], manifestRoot: string, fileOps: SyncFileOps = { writeFileSync }) {
+  const files: Record<string, string> = {}
+  const syncedContentSha256: Record<string, string> = {}
+  const pinnedComponents: Record<string, unknown> = {}
+  for (const key of [...shape].sort()) {
+    safeSegment(key)
+    const component = material.components[key]
+    if (typeof component?.body === 'string') {
+      const relative = `${manifestRoot}/${key}.md`
+      files[key] = relative
+      const target = join(root, ...relative.split('/'))
+      mkdirSync(join(target, '..'), { recursive: true })
+      fileOps.writeFileSync(target, component.body)
+      syncedContentSha256[key] = sha256(component.body)
+    } else if (component?.repoPath && component?.contentSha && component?.commitSha) pinnedComponents[key] = { repoPath: component.repoPath, contentSha: component.contentSha, commitSha: component.commitSha }
+    else throw new Error('instruction_set_unresolvable')
+  }
+  return { profileVersionId: material.profileVersionId, versionNumber: material.versionNumber, modelConfigIdentity: material.modelConfigIdentity, resolvedFrom: material.resolvedFrom, files, syncedContentSha256, ...(Object.keys(pinnedComponents).length ? { pinnedComponents } : {}) }
+}
+
+// Only the scratch paths THIS run created are ever removed; a user's own
+// `.<set>.*.bak` in --out is never touched (PR #1668 review).
+function removeOwnScratch(paths: Array<string | null>) {
+  for (const path of paths) if (path && existsSync(path)) rmSync(path, { recursive: true, force: true })
+}
+
+function existingDestinationIsSynced(destination: string, name: string) {
+  try {
+    if (!statSync(destination).isDirectory()) return false
+    const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8')) as { manifestVersion?: number; name?: string }
+    return manifest.manifestVersion === 1 && manifest.name === name
+  } catch { return false }
+}
+
+export function syncToDisk(out: string, set: SyncSet, fileOps: SyncFileOps = { writeFileSync }) {
+  safeSegment(set.name)
+  for (const key of set.shape) safeSegment(key)
+  const profileSlugs = new Set<string>()
+  for (const profile of set.profiles) {
+    const value = slug(profile.modelConfigIdentity)
+    safeSegment(value)
+    if (profileSlugs.has(value)) throw new Error('instruction_set_slug_collision')
+    profileSlugs.add(value)
+  }
+  mkdirSync(out, { recursive: true })
+  const destination = join(out, set.name)
+  if (existsSync(destination) && !existingDestinationIsSynced(destination, set.name)) throw new Error('instruction_set_sync_destination_not_synced')
+  const temp = join(out, `.${set.name}.${randomUUID()}.tmp`)
+  const move = fileOps.renameSync || renameSync
+  let backup: string | null = null
+  mkdirSync(temp)
+  try {
+    const defaultMaterial = writeMaterial(temp, set.default, set.shape, 'default', fileOps)
+    const profiles = set.profiles.map(profile => ({
+      modelConfigIdentity: profile.modelConfigIdentity, slug: slug(profile.modelConfigIdentity), resolvedFrom: profile.resolvedFrom,
+      production: profile.production ? writeMaterial(temp, profile.production, set.shape, `profiles/${slug(profile.modelConfigIdentity)}`, fileOps) : null,
+    })).sort((a, b) => a.modelConfigIdentity.localeCompare(b.modelConfigIdentity))
+    const components = [
+      ...Object.entries(defaultMaterial.files).map(([key, path]) => ({ key, path, syncedContentSha256: defaultMaterial.syncedContentSha256[key] })),
+      ...profiles.flatMap(profile => profile.production
+        ? Object.entries(profile.production.files).map(([key, path]) => ({ key, modelConfig: profile.modelConfigIdentity, path, syncedContentSha256: profile.production!.syncedContentSha256[key] }))
+        : []),
+    ]
+    const manifest = { manifestVersion: 1, name: set.name, ...(Object.hasOwn(set, 'description') ? { description: set.description ?? null } : {}), shape: set.shape, components, default: defaultMaterial, profiles, ...(set.filteredTo ? { filteredTo: [...set.filteredTo].sort() } : {}) }
+    fileOps.writeFileSync(join(temp, 'manifest.json'), stable(manifest))
+    backup = join(out, `.${set.name}.${randomUUID()}.bak`)
+    if (existsSync(destination)) move(destination, backup)
+    try { move(temp, destination) } catch (error) { if (existsSync(backup)) move(backup, destination); throw error }
+    removeOwnScratch([backup])
+  } catch (error) {
+    removeOwnScratch([temp])
+    if (backup && existsSync(backup) && !existsSync(destination)) move(backup, destination)
+    removeOwnScratch([backup])
+    throw error
+  }
+}
+
+export async function instructionSetsCommand(args: string[], io: InstructionSetsCommandIo): Promise<number> {
+  const positionals = positionalArgs(args)
+  const [subcommand, reference] = positionals
+  if (subcommand === 'default' && reference === 'move') {
+    const version = argValue(args, '--version')
+    if (!version || !/^[0-9]+$/u.test(version) || Number(version) < 1) throw new Error('--version must be a positive integer')
+  }
+  let writeManifest: InstructionSetManifest | undefined
+  if (subcommand === 'create' || subcommand === 'push') {
+    if (!reference || reference.startsWith('--')) throw new Error(subcommand === 'create'
+      ? 'Usage: orizu instructions create <manifest> --project <team/project> [--runner-version <id>] [--model-config <identity>] [--json]'
+      : 'Usage: orizu instructions push <manifest> --project <team/project> [--set <slug-or-exact-name>] [--runner-version <id>] [--json]')
+    writeManifest = loadInstructionSetManifest(reference)
+  }
+  const project = await io.resolveProjectSlug(argValue(args, '--project'))
+  if (subcommand === 'default') {
+    const operation = reference; const set = positionals[2]; const identity = argValue(args, '--model-config'); const version = argValue(args, '--version')
+    if ((operation !== 'show' && operation !== 'move') || !set) throw new Error('Usage: orizu instructions default show|move <set> --project <team/project> [--model-config <identity> --version <n>] [--json]')
+    if (operation === 'move' && (!identity || !version || !/^[0-9]+$/u.test(version) || Number(version) < 1)) throw new Error('--version must be a positive integer')
+    const path = `/api/cli/instruction-sets/${encodeURIComponent(set)}/default?project=${encodeURIComponent(project)}`
+    if (operation === 'show') {
+      const payload = await responsePayload(await authedFetch(path, { method: 'GET' }), 'Instruction sets default show')
+      if (io.json) io.print(JSON.stringify(payload)); else io.print(`Default: v${(payload.default as { versionNumber?: number } | undefined)?.versionNumber ?? '?'}`)
+      return 0
+    }
+    if (!io.json) {
+      const impact = await responsePayload(await authedFetch(path, { method: 'GET' }), 'Instruction sets default show')
+      const resolvesToDefault = Array.isArray(impact.resolvesToDefault) ? impact.resolvesToDefault.filter((item): item is string => typeof item === 'string') : []
+      io.print(`These model configs resolve to the default: ${resolvesToDefault.join(', ')}`)
+    }
+    const payload = await responsePayload(await authedFetch(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ modelConfigIdentity: identity, versionNumber: Number(version) }) }), 'Instruction sets default move')
+    if (io.json) io.print(JSON.stringify(payload)); else io.print(`Default moved to ${identity} v${version}`)
+    return 0
+  }
+  if (subcommand === 'shape') {
+    const operation = reference; const set = positionals[2]; const key = argValue(args, '--key'); const from = argValue(args, '--from')
+    if ((operation !== 'add' && operation !== 'remove') || !set || !key || (operation === 'add' && !from)) throw new Error('Usage: orizu instructions shape add|remove <set> --project <team/project> --key <key> [--from <manifest>] [--json]')
+    let component: { body: string } | undefined
+    if (operation === 'add') {
+      let manifest: unknown
+      try { manifest = JSON.parse(readFileSync(from!, 'utf8')) } catch { throw new Error('instruction_set_manifest_invalid_json') }
+      const source = manifest && typeof manifest === 'object' && Array.isArray((manifest as { components?: unknown }).components)
+        ? (manifest as { components: unknown[] }).components.find((item): item is { key?: unknown; text?: unknown } => Boolean(item && typeof item === 'object' && (item as { key?: unknown }).key === key))
+        : undefined
+      if (!source || typeof source.text !== 'string' || Buffer.byteLength(source.text, 'utf8') > MAX_INSTRUCTION_SET_COMPONENT_BYTES) throw new Error(`Instruction set manifest has no component for key: ${key}`)
+      component = { body: source.text }
+    }
+    const payload = await responsePayload(await authedFetch(`/api/cli/instruction-sets/${encodeURIComponent(set)}/shape?project=${encodeURIComponent(project)}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ operation, key, ...(component ? { component } : {}) }) }), `Instruction sets shape ${operation}`)
+    if (io.json) io.print(JSON.stringify(payload)); else {
+      io.print(`Shape ${operation === 'add' ? 'added' : 'removed'}: ${key}`)
+      const affected = Array.isArray(payload.affected) ? payload.affected : []
+      const identities = [...new Set(affected.flatMap(pointer => pointer && typeof pointer === 'object' && typeof (pointer as { modelConfigIdentity?: unknown }).modelConfigIdentity === 'string' ? [(pointer as { modelConfigIdentity: string }).modelConfigIdentity] : []))]
+      if (identities.length) io.print(`${set} does not resolve for these model configs until the pointers move: ${identities.join(', ')}`)
+      for (const pointer of affected) if (pointer && typeof pointer === 'object') {
+        const item = pointer as { modelConfigIdentity?: unknown; pointer?: unknown; stalePointerVersionNumber?: unknown; headVersionNumber?: unknown; branchedFromVersionNumber?: unknown }
+        if (typeof item.modelConfigIdentity === 'string' && (item.pointer === 'production' || item.pointer === 'default') && typeof item.headVersionNumber === 'number') {
+          const command = item.pointer === 'production' ? 'profiles promote' : 'default move'
+          const operatorAction = item.pointer === 'production' ? 'promote' : 'default move'
+          if (typeof item.stalePointerVersionNumber === 'number' && typeof item.branchedFromVersionNumber === 'number' && item.branchedFromVersionNumber !== item.stalePointerVersionNumber) io.print(`${operatorAction} would move ${item.pointer} from v${item.stalePointerVersionNumber}'s text to v${item.headVersionNumber} = v${item.branchedFromVersionNumber}'s text + ${key}`)
+          io.print(`Follow up: instructions ${command} ${set} --project ${project} --model-config ${item.modelConfigIdentity} --version ${item.headVersionNumber}`)
+        }
+      }
+    }
+    return 0
+  }
+  if (subcommand === 'profiles') {
+    const operation = reference; const set = positionals[2]; const identity = argValue(args, '--model-config')
+    if ((operation !== 'new' && operation !== 'promote' && operation !== 'rollback') || !set || !identity) throw new Error('Usage: orizu instructions profiles new|promote|rollback <set> --project <team/project> --model-config <identity> [--version <n>|--to <n>] [--json]')
+    const encodedSet = encodeURIComponent(set); const encodedIdentity = encodeURIComponent(identity)
+    const version = argValue(args, '--version'); const to = argValue(args, '--to')
+    if ((operation === 'promote' && (!version || !/^[0-9]+$/u.test(version) || Number(version) < 1)) || (operation === 'rollback' && (!to || !/^[0-9]+$/u.test(to) || Number(to) < 1))) throw new Error(operation === 'promote' ? '--version must be a positive integer' : '--to must be a positive integer')
+    const path = operation === 'new' ? `/api/cli/instruction-sets/${encodedSet}/profiles` : operation === 'promote' ? `/api/cli/instruction-sets/${encodedSet}/profiles/${encodedIdentity}/label` : `/api/cli/instruction-sets/${encodedSet}/profiles/${encodedIdentity}/rollback`
+    const body = operation === 'new' ? { modelConfigIdentity: identity } : operation === 'promote' ? { versionNumber: Number(version) } : { to: Number(to) }
+    const payload = await responsePayload(await authedFetch(`${path}?project=${encodeURIComponent(project)}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }), `Instruction sets profiles ${operation}`)
+    if (io.json) io.print(JSON.stringify(payload))
+    else {
+      const profile = payload.profile as { modelConfigIdentity?: string; versionNumber?: number } | undefined
+      io.print(`${profile?.modelConfigIdentity || identity}: v${profile?.versionNumber ?? '?'} ${operation === 'new' ? 'created' : operation === 'promote' ? 'promoted' : 'rolled back'}`)
+      const mirrored = payload.mirroredPromptLabel as { promptName?: unknown; promptId?: unknown } | undefined
+      if (mirrored && (typeof mirrored.promptName === 'string' || typeof mirrored.promptId === 'string')) io.print(`also moved production for prompt ${typeof mirrored.promptName === 'string' ? mirrored.promptName : mirrored.promptId} (default profile → prompt label)`)
+    }
+    return 0
+  }
+  if (subcommand === 'create' || subcommand === 'push') {
+    const manifest = writeManifest!; const modelConfig = argValue(args, '--model-config'); const runnerVersion = argValue(args, '--runner-version')
+    const setReference = argValue(args, '--set') || manifest.name
+    const path = subcommand === 'create' ? '/api/cli/instruction-sets' : `/api/cli/instruction-sets/${encodeURIComponent(setReference)}/versions`
+    const body = subcommand === 'create'
+      ? { ...manifest, ...(modelConfig ? { modelConfigIdentity: modelConfig } : {}), ...(runnerVersion ? { runnerVersionId: runnerVersion } : {}) }
+      : { shape: manifest.shape, components: manifest.components, ...(Object.hasOwn(manifest, 'description') ? { description: manifest.description } : {}), ...(runnerVersion ? { runnerVersionId: runnerVersion } : {}) }
+    const payload = await responsePayload(await authedFetch(`${path}?project=${encodeURIComponent(project)}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }), `Instruction sets ${subcommand}`)
+    if (io.json) io.print(JSON.stringify(payload))
+    else {
+      const set = payload.instructionSet as { name?: string; profiles?: unknown[] } | undefined
+      const pushed = Array.isArray(payload.pushed) ? payload.pushed : []
+      const unchanged = Array.isArray(payload.unchanged) ? payload.unchanged : []
+      const skipped = Array.isArray(payload.skipped) ? payload.skipped : []
+      if (subcommand === 'create') {
+        const profiles = Array.isArray(set?.profiles) ? set.profiles : []
+        io.print(`${set?.name || manifest.name}: ${profiles.length} profile(s) created`)
+      } else {
+        const describe = (value: unknown) => {
+          if (typeof value === 'string') return value
+          if (value && typeof value === 'object') {
+            const row = value as { modelConfigIdentity?: unknown; versionNumber?: unknown }
+            return `${typeof row.modelConfigIdentity === 'string' ? row.modelConfigIdentity : 'unknown'}${typeof row.versionNumber === 'number' ? ` v${row.versionNumber}` : ''}`
+          }
+          return 'unknown'
+        }
+        io.print(`${set?.name || manifest.name}: pushed ${pushed.map(describe).join(', ') || 'none'}; unchanged ${unchanged.map(describe).join(', ') || 'none'}; skipped ${skipped.map(describe).join(', ') || 'none'}`)
+      }
+    }
+    return 0
+  }
+  if (subcommand === 'archive' || subcommand === 'restore') {
+    if (!reference || reference.startsWith('--')) throw new Error(`Usage: orizu instructions ${subcommand} <slug-or-exact-name> --project <team/project> [--json]`)
+    const archived = subcommand === 'archive'
+    const payload = await responsePayload(await authedFetch(`/api/cli/instruction-sets/${encodeURIComponent(reference)}?project=${encodeURIComponent(project)}`, {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ archived }),
+    }), `Instructions ${subcommand}`)
+    if (io.json) io.print(JSON.stringify(payload))
+    else {
+      const set = payload.instructionSet as { name?: string; slug?: string } | undefined
+      const identity = set?.slug && set.slug !== set.name ? `${set.name || reference} (${set.slug})` : set?.name || set?.slug || reference
+      io.print(`${archived ? 'Archived' : 'Restored'} instruction set ${identity}`)
+    }
+    return 0
+  }
+  const status = argValue(args, '--status') || 'active'
+  if (subcommand !== 'list' && subcommand !== 'show' && subcommand !== 'sync') throw new Error('Usage: orizu instructions list|show|sync|archive|restore')
+  if (subcommand === 'sync') {
+    const output = argValue(args, '--out')
+    if (!reference || !output) throw new Error('Usage: orizu instructions sync <set> --out <dir> --project <team/project> [--model-config <identity>] [--json]')
+    const modelConfig = argValue(args, '--model-config')
+    const path = `/api/cli/instruction-sets/${encodeURIComponent(reference)}/sync?project=${encodeURIComponent(project)}${modelConfig ? `&modelConfig=${encodeURIComponent(modelConfig)}` : ''}`
+    const payload = await responsePayload(await authedFetch(path, { method: 'GET' }), 'Instruction sets sync')
+    const set = payload.instructionSet as SyncSet
+    if (!set || (set.slug !== reference && set.name !== reference) || (modelConfig && (!Array.isArray(set.filteredTo) || set.filteredTo.length !== 1 || set.filteredTo[0] !== modelConfig))) {
+      throw new Error('instruction_set_sync_response_mismatch')
+    }
+    syncToDisk(output, set)
+    if (io.json) io.print(JSON.stringify(payload)); else io.print(`Synced ${set.name} to ${join(output, set.name)}`)
+    return 0
+  }
+  if (subcommand === 'show' && (!reference || reference.startsWith('--'))) throw new Error('Instruction set name is required')
+  if (status !== 'active' && status !== 'archived' && status !== 'all') throw new Error('--status must be active, archived, or all')
+
+  const query = `project=${encodeURIComponent(project)}&status=${encodeURIComponent(status)}`
+  const path = subcommand === 'list'
+    ? `/api/cli/instruction-sets?${query}`
+    : `/api/cli/instruction-sets/${encodeURIComponent(reference!)}?${query}`
+  const payload = await responsePayload(await authedFetch(path, { method: 'GET' }), `Instruction sets ${subcommand}`)
+  if (io.json) {
+    io.print(JSON.stringify(payload))
+    return 0
+  }
+  if (subcommand === 'list') {
+    const sets = Array.isArray(payload.instructionSets) ? payload.instructionSets : []
+    for (const item of sets) {
+      const set = item as { name?: string; slug?: string; description?: string | null; shape?: string[]; status?: string }
+      io.print(`${set.name || 'unnamed'}${set.slug ? ` [${set.slug}]` : ''}${set.status === 'archived' ? ' [archived]' : ''}${set.shape ? ` (${set.shape.join(', ')})` : ''}`)
+      if (set.description) io.print(`  ${sanitizeHumanInlineText(sanitizeTerminalText, set.description)}`)
+    }
+    return 0
+  }
+  const set = payload.instructionSet as { name?: string; description?: string | null; shape?: string[]; status?: string; default?: { versionNumber?: number } | null; profiles?: Array<{ modelConfigIdentity?: string | null; production?: { versionNumber?: number } | null; latestVersionNumber?: number | null }> } | undefined
+  io.print(`${set?.name || reference}${set?.status === 'archived' ? ' [archived]' : ''}: ${set?.shape?.join(', ') || ''}`)
+  if (set?.description) io.print(`Description: ${sanitizeHumanInlineText(sanitizeTerminalText, set.description)}`)
+  if (set?.default) io.print(`Default: v${set.default.versionNumber ?? '?'}`)
+  for (const profile of set?.profiles || []) {
+    io.print(`${profile.modelConfigIdentity || 'unspecified'}: production ${profile.production ? `v${profile.production.versionNumber}` : '—'}, latest ${profile.latestVersionNumber ?? '—'}`)
+  }
+  return 0
+}

package/src/markdown-report-input.ts

@@ -1,6 +1,8 @@
 import { readFileSync } from 'fs'
 import { basename } from 'path'
 
+import { hasCanonicalReportMarkdownContent } from './report-markdown-blankness.js'
+
 export const MARKDOWN_REPORT_MAX_BYTES = 2 * 1024 * 1024
 
 function getArg(args: readonly string[], name: string): string | null {
@@ -20,6 +22,12 @@ function rejectDashPrefixedOptionValue(name: string, value: string | null) {
   }
 }
 
+function rejectMissingOptionValue(args: readonly string[], name: string) {
+  if (args.some((arg, index) => arg === name && index + 1 >= args.length)) {
+    throw new Error(`${name} requires a value`)
+  }
+}
+
 function readSourceFile(pathArg: string): string {
   const expandedPath = expandHomePath(pathArg)
   try {
@@ -42,6 +50,16 @@ export function readMarkdownReportInput(
   args: readonly string[],
   reportLabel: 'Optimization' | 'Prompt' | 'Task'
 ): MarkdownReportInput | null {
+  if (args.some(arg => arg.startsWith('--report='))) {
+    throw new Error('use --report <markdown|@file> with a space, not =')
+  }
+  if (args.some(arg => arg.startsWith('--report-file='))) {
+    throw new Error('use --report-file <path> with a space, not =')
+  }
+
+  rejectMissingOptionValue(args, '--report')
+  rejectMissingOptionValue(args, '--report-file')
+
   const report = getArg(args, '--report')
   const reportFile = getArg(args, '--report-file')
 
@@ -69,7 +87,7 @@ export function readMarkdownReportInput(
     sourceName = 'inline'
   }
 
-  if (!markdown.trim()) {
+  if (!hasCanonicalReportMarkdownContent(markdown)) {
     throw new Error(`${reportLabel} report markdown must not be blank`)
   }
   if (Buffer.byteLength(markdown, 'utf8') > MARKDOWN_REPORT_MAX_BYTES) {

package/src/model-configs-cli.ts

@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs'
+
+import { authedFetch } from './http.js'
+
+export type CliFetcher = (path: string, init?: RequestInit) => Promise<Response>
+
+export interface ModelConfigSettingsVersion {
+  versionNumber: number
+  settings: Record<string, unknown>
+}
+
+export interface ModelConfig {
+  identity: string
+  displayName: string
+  currentSettingsVersion: ModelConfigSettingsVersion
+  createdAt: string
+}
+
+export interface ModelConfigsCommandIo {
+  json: boolean
+  print: (line: string) => void
+  fetcher?: CliFetcher
+  resolveProjectSlug?: (arg: string | null) => Promise<string>
+}
+
+function argValue(args: string[], flag: string): string | null {
+  const index = args.lastIndexOf(flag)
+  return index === -1 || !args[index + 1] || args[index + 1]!.startsWith('--') ? null : args[index + 1]!
+}
+
+function positionalArgs(args: string[]): string[] {
+  const values: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index]!.startsWith('--')) {
+      if (args[index + 1] && !args[index + 1]!.startsWith('--')) index += 1
+    } else values.push(args[index]!)
+  }
+  return values
+}
+
+function readSettings(value: string | null, defaultToEmpty = false): Record<string, unknown> {
+  if (!value) {
+    if (defaultToEmpty) return {}
+    throw new Error('--settings is required')
+  }
+  const source = value.startsWith('@') ? readFileSync(value.slice(1), 'utf8') : value
+  const parsed: unknown = JSON.parse(source)
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error('--settings must contain a JSON object')
+  }
+  return parsed as Record<string, unknown>
+}
+
+async function responseMessage(response: Response): Promise<string> {
+  try {
+    const body = await response.clone().json() as Record<string, unknown>
+    return typeof body.error === 'string' ? body.error : response.statusText
+  } catch {
+    return response.statusText
+  }
+}
+
+async function requestJson(fetcher: CliFetcher, path: string, init?: RequestInit): Promise<unknown> {
+  const response = await fetcher(path, init)
+  if (!response.ok) throw new Error(`Model config request failed (${response.status}): ${await responseMessage(response)}`)
+  return response.json()
+}
+
+function renderModelConfig(config: ModelConfig): string {
+  return `${config.identity}  ${config.displayName}  v${config.currentSettingsVersion.versionNumber}`
+}
+
+export async function modelConfigsCommand(args: string[], io: ModelConfigsCommandIo): Promise<number> {
+  const positional = positionalArgs(args)
+  const [command, action, identity] = positional
+  const resolveProjectSlug = io.resolveProjectSlug
+  if (!resolveProjectSlug) throw new Error('Project resolver unavailable')
+  const projectArg = argValue(args, '--project')
+  const project = projectArg || await resolveProjectSlug(null)
+  const fetcher = io.fetcher ?? authedFetch
+  const root = `/api/cli/model-configs?project=${encodeURIComponent(project)}`
+  let result: unknown
+
+  if (command === 'list' && !action) {
+    result = await requestJson(fetcher, root, { method: 'GET' })
+    if (io.json) io.print(JSON.stringify(result))
+    else for (const config of ((result as { modelConfigs?: ModelConfig[] }).modelConfigs || [])) io.print(renderModelConfig(config))
+    return 0
+  }
+  if (command === 'show' && action && !identity) {
+    result = await requestJson(fetcher, `/api/cli/model-configs/${encodeURIComponent(action)}?project=${encodeURIComponent(project)}`, { method: 'GET' })
+  } else if (command === 'create' && action && !identity) {
+    result = await requestJson(fetcher, root, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ identity: action, displayName: argValue(args, '--name') || action, settings: readSettings(argValue(args, '--settings'), true) }),
+    })
+  } else if (command === 'settings' && action === 'set' && identity) {
+    result = await requestJson(fetcher, `/api/cli/model-configs/${encodeURIComponent(identity)}/settings?project=${encodeURIComponent(project)}`, {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ settings: readSettings(argValue(args, '--settings')) }),
+    })
+  } else if (command === 'copy' && action && !identity) {
+    const to = argValue(args, '--to')
+    if (!to) throw new Error('--to is required')
+    result = await requestJson(fetcher, `/api/cli/model-configs/${encodeURIComponent(action)}/copy?project=${encodeURIComponent(project)}`, {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ to }),
+    })
+  } else {
+    io.print('Usage: orizu model-configs <create|list|show|settings set|copy> [--project <team/project>] [--json]')
+    return 1
+  }
+
+  if (io.json) {
+    io.print(JSON.stringify(result))
+  } else {
+    const config = (result as { modelConfig: ModelConfig }).modelConfig
+    io.print(renderModelConfig(config))
+  }
+  return 0
+}

package/src/optimizations-promote-cli.ts

@@ -0,0 +1,41 @@
+import { extractErrorMessage } from './error-response.js'
+import { sanitizeTerminalText } from './json-response.js'
+
+export interface OptimizationsPromoteIo {
+  json: boolean
+  print: (line: string) => void
+  resolveProjectSlug: (projectArg: string | null) => Promise<string>
+  fetcher: (path: string, init?: RequestInit) => Promise<Response>
+}
+
+function option(args: readonly string[], name: string): string | null {
+  const index = args.indexOf(name)
+  return index === -1 || !args[index + 1] || args[index + 1].startsWith('--') ? null : args[index + 1]
+}
+
+export async function promoteOptimizationCommand(args: string[], io: OptimizationsPromoteIo): Promise<void> {
+  const runId = args.find(arg => !arg.startsWith('--') && arg !== option(args, '--candidate') && arg !== option(args, '--label') && arg !== option(args, '--project'))
+  const candidateId = option(args, '--candidate')
+  const label = option(args, '--label')
+  if (!runId || !candidateId || (label !== null && label !== 'production')) {
+    throw new Error('Usage: orizu optimizations promote <run-id> --candidate <id> [--label production] [--project <team/project>] [--json]')
+  }
+  const project = await io.resolveProjectSlug(option(args, '--project'))
+  const response = await io.fetcher(`/api/cli/optimization-runs/${encodeURIComponent(runId)}/promote?project=${encodeURIComponent(project)}`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ candidateId, label }),
+  })
+  if (!response.ok) throw new Error(`Failed to promote optimization candidate: ${await extractErrorMessage(response)}`)
+  const data = await response.json() as { promptVersionId?: string; profileVersionId?: string; components?: Array<{ key: string; status: string }> }
+  if (io.json) {
+    io.print(JSON.stringify(data.profileVersionId
+      ? { profileVersionId: data.profileVersionId, components: data.components ?? [] }
+      : { promptVersionId: data.promptVersionId }))
+    return
+  }
+  if (data.profileVersionId) {
+    io.print(`Promoted profile version ${sanitizeTerminalText(data.profileVersionId)}`)
+    for (const component of data.components ?? []) io.print(`${sanitizeTerminalText(component.key)}: ${sanitizeTerminalText(component.status)}`)
+    return
+  }
+  io.print(`Promoted prompt version ${sanitizeTerminalText(data.promptVersionId ?? '')}`)
+}