@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import type { CliHandlerOverrides, CliIo, CliRuntime } from './cli-main.js';
+export type { CliHandlerOverrides, CliIo, CliRuntime, CommandHandlers, CommandOutcome, ComposeScaffoldRequest, } from './cli-main.js';
+export declare function runCli(args: readonly string[], io?: CliIo, handlerOverrides?: CliHandlerOverrides, runtime?: CliRuntime): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,16 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { commandSpelling } from './command-table.js';
+import { runGuardCommand } from './cli-guard.js';
+// The shell guard runs this entry on every agent tool call, so a guard decision loads only its own
+// modules; every other command loads the full CLI. Native Windows goes to the full CLI for its refusal.
+export async function runCli(args, io = process, handlerOverrides = {}, runtime = {}) {
+    if (process.platform !== 'win32' && commandSpelling(args).name === 'guard-evaluate') {
+        return runGuardCommand(commandSpelling(args).rest, io, runtime.env ?? process.env);
+    }
+    return (await import('./cli-main.js')).runCli(args, io, handlerOverrides, runtime);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(resolve(process.argv[1]))).href) {
+    process.exitCode = await runCli(process.argv.slice(2));
+}

package/dist/command-table.d.ts

@@ -0,0 +1,121 @@
+import type { ParseArgsConfig } from 'node:util';
+import { type GuardInvocationProfile } from './guards/evaluator.js';
+import { GUARD_HANDLER_ARGV } from './guards/harness-adapter.js';
+export declare function isRecordedAnswerField(value: string): boolean;
+export type WorkHandlerIdentifier = 'work-status' | 'work-accept' | 'work-check' | 'work-note' | 'work-decide' | 'work-answer' | 'work-acknowledge' | 'work-grade' | 'work-signoff' | 'work-recover' | 'work-verify' | 'grade-criteria' | 'browser-drive' | 'browser-screenshot' | 'test-run';
+export type HandlerIdentifier = WorkHandlerIdentifier | 'check' | 'confirm' | 'docs-check' | 'doctor' | 'down' | 'exec' | 'init' | 'logs' | 'preflight' | 'ps' | 'rebuild' | 'registry-resolve' | 'reset' | 'restart' | 'runtime' | 'setup' | 'selftest' | 'sibling' | 'tool' | 'session' | 'sleep' | 'stacks' | 'sync' | 'up' | 'upgrade' | 'use' | 'pull';
+type CommandStage = 'set-up' | 'generate-and-verify' | 'run-the-stack' | 'diagnose' | 'test-and-grade';
+/** The order a newcomer meets the commands in, as the README's "Commands at a glance" table names it. */
+export declare const commandStages: readonly Readonly<{
+    id: CommandStage;
+    title: string;
+}>[];
+/**
+ * A group is a first command word whose commands are named `<group> <subcommand>`. Each subcommand
+ * keeps its own row, options and handler, so an option one subcommand reads is never accepted and
+ * ignored by another.
+ */
+export declare const commandGroups: readonly Readonly<{
+    name: string;
+    summary: string;
+}>[];
+/**
+ * The public command an argv names, and the arguments after it. A group word takes the next word
+ * as its subcommand; `subcommand` is absent when none follows, so the caller can show the group.
+ */
+export declare function commandSpelling(args: readonly string[]): Readonly<{
+    name: string | undefined;
+    group?: string;
+    rest: readonly string[];
+}>;
+export interface CommandDefinition {
+    /** The words a person types: one word, or `<group> <subcommand>` for a member of commandGroups. */
+    name: string;
+    stage: CommandStage;
+    summary: string;
+    /** What follows the command name in its help usage line, when it takes more than options. */
+    usage?: string;
+    handler: HandlerIdentifier;
+    options: NonNullable<ParseArgsConfig['options']>;
+    visibility: 'public';
+    ordinary: OrdinaryCommandMetadata;
+}
+export declare function describePublicOption(name: string): string;
+type OrdinaryValueRole = 'confined-path' | 'resolved-config' | 'declared-service' | 'declared-gate' | 'gate-mode' | 'gate-selector' | 'identifier' | 'route' | 'label' | 'field' | 'tail' | 'since' | 'sha256' | 'surface-target' | 'local-image' | 'evaluator-tool' | 'compose-profile';
+interface OrdinaryOption {
+    readonly kind: 'flag' | 'value';
+    readonly role: 'boolean' | OrdinaryValueRole;
+    readonly repetition: 'singleton' | 'repeated';
+    readonly required?: true;
+}
+type OrdinaryCommandMetadata = Readonly<{
+    availability: 'unavailable';
+    reason: string;
+}> | Readonly<{
+    availability: 'available';
+    executableRole: 'installed-cockpit';
+    command: HandlerIdentifier;
+    positional: Readonly<{
+        min: number;
+        max: number;
+        roles: readonly ['confined-root'] | readonly ['operation'] | readonly ['version'] | readonly ['slug', 'confined-root'] | readonly ['operation', 'surface-target'] | readonly [];
+        operations?: readonly string[];
+    }>;
+    options: Readonly<Record<string, OrdinaryOption>>;
+    cwdRole: 'canonical-root';
+    configuration: 'resolved' | 'none';
+    forbidden: Readonly<{
+        presence: readonly string[];
+    }>;
+    admittedWhileUnsynced?: true;
+    requires?: OrdinaryGrant;
+}>;
+export declare function isWorkHandler(value: HandlerIdentifier): value is WorkHandlerIdentifier;
+export declare const commands: readonly CommandDefinition[];
+interface InternalCommandDefinition {
+    readonly name: 'guard-evaluate';
+    readonly handler: 'guard-evaluate';
+    readonly visibility: 'internal';
+    readonly ordinary: Readonly<{
+        availability: 'unavailable';
+        reason: string;
+    }>;
+    readonly argv: typeof GUARD_HANDLER_ARGV;
+    readonly options: Readonly<{
+        harness: {
+            readonly type: 'string';
+        };
+    }>;
+}
+export declare const internalCommands: readonly InternalCommandDefinition[];
+interface OrdinaryInvocationAuthority {
+    readonly executable: string;
+    readonly canonicalRoot: string;
+    readonly allowedRoots: readonly string[];
+    readonly configPath: string;
+    readonly services: readonly string[];
+    /** Test gate ids the configuration declares. */
+    readonly gates: readonly string[];
+    /** What the configuration grants an agent: browser preapproval, and the [autonomy] decisions set to agent. */
+    readonly grants: readonly OrdinaryGrant[];
+    /** Compose profiles an agent may name with --profile; any other starts services no person declared for it. */
+    readonly profiles: readonly string[];
+}
+export type OrdinaryGrant = 'browser-preapproval' | 'autonomy-sync' | 'autonomy-reset';
+/** The commands the guard admits while a non-widening edit of cockpit.toml waits for sync. */
+export declare const UNSYNCED_ADMITTED_COMMANDS: readonly string[];
+/** The same commands as prose, for the hold that names them: "cockpit sync and check". */
+export declare const UNSYNCED_ADMITTED_PROSE: string;
+/**
+ * The inner command of an exact `session --config <configured file> -- <command…>` run from the
+ * cockpit root, or undefined. The guard admits the session only when it admits the inner command,
+ * so a session never runs what the agent could not run directly.
+ */
+export declare function ordinarySessionCommand(argv: readonly string[], cwd: string, authority: Readonly<{
+    canonicalRoot: string;
+    configPath: string;
+    profiles: readonly string[];
+}>): readonly string[] | undefined;
+/** Classify one exact candidate; the caller authenticates filesystem and executable authority. */
+export declare function resolveOrdinaryInvocation(input: GuardInvocationProfile, authority: OrdinaryInvocationAuthority, inspectPath: (path: string) => boolean): GuardInvocationProfile | undefined;
+export {};