fjall 0.95.0 → 0.99.1

package/bin/assets/src/util/agent/mcpProtocolEmit.d.ts

@@ -0,0 +1,31 @@
+import { type McpStepStatus } from "@fjall/util/mcpProtocol";
+export interface McpProtocolEmitter {
+    stepStart(stepId: string, name: string, index: number, total: number): Promise<void>;
+    stepComplete(stepId: string, name: string, status: McpStepStatus, index: number, total: number, errorMessage?: string): Promise<void>;
+    warning(message: string): Promise<void>;
+    result(data: unknown): Promise<void>;
+    error(code: string, message: string, details?: Record<string, unknown>): Promise<void>;
+}
+export interface CreateMcpProtocolEmitterOptions {
+    readonly write?: (chunk: string) => Promise<void>;
+}
+/**
+ * Build a stdout emitter that serialises every frame onto a single
+ * promise chain.
+ *
+ *   1. Frame order matches call order (each write awaits the previous).
+ *   2. `await emitter.result(...)` / `.error(...)` drains in-flight
+ *      writes — callers can fire-and-forget intermediate progress
+ *      frames.
+ *   3. `safeParse` validation precedes every write; a protocol
+ *      violation rejects the returned promise (and propagates through
+ *      the chain) rather than throwing synchronously.
+ *   4. A failed write (EPIPE / closed pipe) is logged once at warn
+ *      level and the chain is reset so subsequent frames still attempt
+ *      emission. Write failures NEVER silently no-op the rest of the
+ *      stream.
+ *
+ * Masking happens BEFORE `JSON.stringify` on every user-derived string
+ * field (security-standards "Mask Before You Truncate").
+ */
+export declare function createMcpProtocolEmitter(options?: CreateMcpProtocolEmitterOptions): McpProtocolEmitter;

package/bin/assets/src/util/agent/mcpProtocolEmit.js

@@ -0,0 +1,2 @@
+import{maskSensitiveOutput as i}from"@fjall/util";import{MCP_PROTOCOL_VERSION as f,McpProtocolFrameSchema as l}from"@fjall/util/mcpProtocol";import{logger as g}from"../logger/index.js";const P="McpProtocolEmit";function u(e){if(typeof e=="string")return i(e);if(Array.isArray(e))return e.map(u);if(e!==null&&typeof e=="object"){const a={};for(const[c,t]of Object.entries(e))a[c]=u(t);return a}return e}const w=e=>new Promise((a,c)=>{process.stdout.write(e,t=>{t?c(t):a()})});function S(e={}){const a=e.write??w;let c=Promise.resolve();function t(r){const n=l.safeParse(r);if(!n.success){const s=Promise.reject(new Error(`Invalid MCP frame: ${n.error.message}`));return c=s.catch(()=>{}),s}const o=JSON.stringify(n.data)+`
+`,m=c.then(()=>a(o));return c=m.catch(s=>{g.warn(P,"Frame write failed",{error:i(s instanceof Error?s.message:String(s))})}),m}return{stepStart(r,n,o,m){return t({v:f,kind:"step.start",stepId:r,name:i(n),index:o,total:m})},stepComplete(r,n,o,m,s,p){const d={v:f,kind:"step.complete",stepId:r,name:i(n),status:o,index:m,total:s,...p!==void 0&&{errorMessage:i(p)}};return t(d)},warning(r){return t({v:f,kind:"warning",message:i(r)})},result(r){return t({v:f,kind:"result",data:u(r)})},error(r,n,o){return t({v:f,kind:"error",error:{code:i(r),message:i(n),...o!==void 0&&{details:u(o)}}})}}}export{S as createMcpProtocolEmitter};

package/bin/assets/src/util/agent/schemas/appsSchemas.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agent output schemas for apps + status commands.
+ * Defines field schemas and tabular projections for TOON rendering.
+ */
+import type { AgentSchema, TabularSchema } from "./types.js";
+import type { AppSummary, AppDetail, AppListData } from "../../../services/app/AppQueryService.js";
+export declare const APPS_LIST_TABULAR: TabularSchema<AppSummary>;
+export declare function buildAppsListAggregates(data: AppListData): Record<string, number>;
+export declare const APPS_DESCRIBE_SCHEMA: AgentSchema;
+export declare function buildAppDescribeData(detail: AppDetail): Record<string, unknown>;
+export declare const APPS_CREATE_SCHEMA: AgentSchema;
+/**
+ * Schema for the dry-run preview emitted by `fjall apps create --dry-run --agent`.
+ * Mirrors `DryRunArtefactsSchema` in `cli/src/operations/types.ts` so the CLI
+ * and MCP wires stay in lockstep.
+ */
+export declare const APPS_CREATE_DRY_RUN_SCHEMA: AgentSchema;
+export declare const STATUS_TABULAR: TabularSchema<AppSummary>;

package/bin/assets/src/util/agent/schemas/appsSchemas.js

@@ -0,0 +1 @@
+const t={fields:["name","health"],project:e=>({name:e.name,health:e.health})};function a(e){return{total:e.totalCount,healthy:e.healthy,unhealthy:e.unhealthy,deploying:e.deploying}}const n={entity:"app",defaultFields:["name","health","id"],extraFields:{},aggregates:[]};function l(e){return{name:e.name,health:e.health,id:e.id,...typeof e.application=="object"&&e.application!==null?e.application:{}}}const o={entity:"app",defaultFields:["name"],extraFields:{},aggregates:[]},p={entity:"plan",defaultFields:["name","mode","fileCount","npmPackages","registryActions"],extraFields:{},aggregates:[]},h={fields:["name","health"],project:e=>({name:e.name,health:e.health})};export{p as APPS_CREATE_DRY_RUN_SCHEMA,o as APPS_CREATE_SCHEMA,n as APPS_DESCRIBE_SCHEMA,t as APPS_LIST_TABULAR,h as STATUS_TABULAR,l as buildAppDescribeData,a as buildAppsListAggregates};

package/bin/assets/src/util/agent/schemas/assetSchemas.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent output schemas for asset commands.
+ * Defines field schemas and tabular projections for TOON rendering.
+ */
+import type { AgentSchema, TabularSchema } from "./types.js";
+import type { AssetSummary, ComplianceIssueSummary } from "../../api/FjallApiClient.types.js";
+export declare const ASSETS_LIST_TABULAR: TabularSchema<AssetSummary>;
+export declare function buildAssetsListAggregates(assets: readonly AssetSummary[]): Record<string, number>;
+export declare const ASSETS_DETAIL_SCHEMA: AgentSchema;
+export declare const ASSETS_COMPLIANCE_TABULAR: TabularSchema<ComplianceIssueSummary>;
+export declare function buildComplianceAggregates(issues: readonly ComplianceIssueSummary[]): Record<string, number>;
+export declare const ASSETS_SUMMARY_SCHEMA: AgentSchema;
+export declare function buildAssetsSummary(assets: readonly AssetSummary[]): Record<string, number>;

package/bin/assets/src/util/agent/schemas/assetSchemas.js

@@ -0,0 +1 @@
+const r={fields:["name","type","region","status"],project:t=>({name:t.name,type:t.type,region:t.region??"",status:t.status})};function i(t){let a=0,s=0;for(const e of t)e.status==="active"?a++:e.status==="deleted"&&s++;return{total:t.length,active:a,deleted:s}}const o={entity:"asset",defaultFields:["name","type","region","status","assetIdentifier","provider"],extraFields:{id:{path:"id"},accountId:{path:"accountId"},iacStatus:{path:"iacStatus"},estimatedMonthlyCost:{path:"estimatedMonthlyCost",transform:"currency"},lastSeenAt:{path:"lastSeenAt",transform:"relativeTime"},createdAt:{path:"createdAt",transform:"relativeTime"},updatedAt:{path:"updatedAt",transform:"relativeTime"}},aggregates:[]},l={fields:["title","severity","status","ruleId"],project:t=>({title:t.title,severity:t.severity,status:t.status,ruleId:t.ruleId})};function n(t){let a=0,s=0;for(const e of t)e.severity==="critical"?a++:e.severity==="high"&&s++;return{total:t.length,critical:a,high:s}}const u={entity:"asset_summary",defaultFields:["total","active","withIssues"],extraFields:{},aggregates:[]};function c(t){let a=0,s=0;for(const e of t)e.status==="active"&&a++,e._count&&e._count.complianceIssues>0&&s++;return{total:t.length,active:a,withIssues:s}}export{l as ASSETS_COMPLIANCE_TABULAR,o as ASSETS_DETAIL_SCHEMA,r as ASSETS_LIST_TABULAR,u as ASSETS_SUMMARY_SCHEMA,i as buildAssetsListAggregates,c as buildAssetsSummary,n as buildComplianceAggregates};

package/bin/assets/src/util/agent/schemas/awsSchemas.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Agent output schemas for AWS commands: aws exec.
+ */
+import type { AgentSchema } from "./types.js";
+export declare const AWS_EXEC_SCHEMA: AgentSchema;

package/bin/assets/src/util/agent/schemas/awsSchemas.js

@@ -0,0 +1 @@
+const e={entity:"exec",defaultFields:["exitCode"],extraFields:{command:{path:"command"},target:{path:"target"},region:{path:"region"}},aggregates:[]};export{e as AWS_EXEC_SCHEMA};

package/bin/assets/src/util/agent/schemas/deploySchemas.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Agent output schemas for deploy, destroy, and build commands.
+ * These are streaming commands — they emit multiple TOON blocks.
+ */
+import type { AgentSchema } from "./types.js";
+export declare const DEPLOY_SCHEMA: AgentSchema;
+export declare const DESTROY_SCHEMA: AgentSchema;
+export declare const BUILD_SCHEMA: AgentSchema;

package/bin/assets/src/util/agent/schemas/deploySchemas.js

@@ -0,0 +1 @@
+const t={entity:"deployment",defaultFields:["target","status","duration"],extraFields:{stackName:{path:"stackName"},outputs:{path:"outputs"}},aggregates:[]},a={entity:"destroy",defaultFields:["target","status","duration"],extraFields:{},aggregates:[]},e={entity:"build",defaultFields:["app","imageUrl","status"],extraFields:{tag:{path:"tag"},duration:{path:"duration"}},aggregates:[]};export{e as BUILD_SCHEMA,t as DEPLOY_SCHEMA,a as DESTROY_SCHEMA};

package/bin/assets/src/util/agent/schemas/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Barrel for agent output schema types and per-command schemas.
+ */
+export type { ActionRequired, Aggregate, AgentError, AgentSchema, FieldSource, StreamEvent, TabularSchema, TransformName } from "./types.js";
+export * from "./appsSchemas.js";
+export * from "./secretsSchemas.js";
+export * from "./userSchemas.js";
+export * from "./deploySchemas.js";
+export * from "./infraSchemas.js";
+export * from "./assetSchemas.js";

package/bin/assets/src/util/agent/schemas/index.js

@@ -0,0 +1 @@
+export*from"./appsSchemas.js";export*from"./secretsSchemas.js";export*from"./userSchemas.js";export*from"./deploySchemas.js";export*from"./infraSchemas.js";export*from"./assetSchemas.js";

package/bin/assets/src/util/agent/schemas/infraSchemas.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Agent output schemas for infrastructure commands:
+ * connect, login, list, add, tunnel, target, domain, create (account/org),
+ * restore, import, sync.
+ */
+import type { DerivedTarget } from "@fjall/util";
+import type { AgentSchema, TabularSchema } from "./types.js";
+export declare const CONNECT_SCHEMA: AgentSchema;
+export declare const LOGIN_SCHEMA: AgentSchema;
+export declare const LIST_SCHEMA: AgentSchema;
+export declare const LIST_TABULAR: TabularSchema<{
+    type: string;
+    name: string;
+    filePath: string;
+    start: number;
+    length: number;
+}>;
+export declare const ADD_SCHEMA: AgentSchema;
+export declare const HISTORY_SCHEMA: AgentSchema;
+export declare const HISTORY_TABULAR: TabularSchema<{
+    timestamp: string;
+    path: string;
+    sizeBytes: number;
+}>;
+export declare const TUNNEL_SCHEMA: AgentSchema;
+export declare const TARGET_LIST_SCHEMA: AgentSchema;
+export declare const TARGET_LIST_TABULAR: TabularSchema<DerivedTarget & {
+    active: boolean;
+}>;
+export declare const TARGET_GET_SCHEMA: AgentSchema;
+export declare const TARGET_SET_SCHEMA: AgentSchema;
+export declare const DOMAIN_LIST_SCHEMA: AgentSchema;
+export declare const DOMAIN_LIST_TABULAR: TabularSchema<{
+    name: string;
+    status: string;
+}>;
+export declare const DOMAIN_VERIFY_SCHEMA: AgentSchema;
+export declare const DOMAIN_EXPORT_SCHEMA: AgentSchema;
+export declare const DOMAIN_IMPORT_SCHEMA: AgentSchema;
+export declare const CREATE_DOMAIN_SCHEMA: AgentSchema;
+export declare const CREATE_ACCOUNT_SCHEMA: AgentSchema;
+export declare const CREATE_ORG_SCHEMA: AgentSchema;
+export declare const RESTORE_SCHEMA: AgentSchema;
+export declare const IMPORT_SCHEMA: AgentSchema;
+export declare const SYNC_SCHEMA: AgentSchema;

package/bin/assets/src/util/agent/schemas/infraSchemas.js

@@ -0,0 +1 @@
+const e={entity:"connection",defaultFields:["environment","status"],extraFields:{accountId:{path:"accountId"},region:{path:"region"}},aggregates:[]},a={entity:"login",defaultFields:["status","email"],extraFields:{},aggregates:[]},n={entity:"resources",defaultFields:["type","name","filePath"],extraFields:{start:{path:"start"},length:{path:"length"}},aggregates:[{name:"total",compute:"count"}]},o={fields:["type","name","filePath"],project:t=>({type:t.type,name:t.name,filePath:t.filePath})},s={entity:"resource",defaultFields:["type","name","status"],extraFields:{},aggregates:[]},r={entity:"snapshots",defaultFields:["timestamp","path","sizeBytes"],extraFields:{},aggregates:[{name:"total",compute:"count"}]},i={fields:["timestamp","path","sizeBytes"],project:t=>({timestamp:t.timestamp,path:t.path,sizeBytes:t.sizeBytes})},c={entity:"tunnel",defaultFields:["localPort","target","status"],extraFields:{host:{path:"host"},remotePort:{path:"remotePort"}},aggregates:[]},l={entity:"targets",defaultFields:["name","environment","accountName","region"],extraFields:{accountId:{path:"accountId"},active:{path:"active"}},aggregates:[{name:"totalCount",compute:"count"}]},p={fields:["name","environment","accountName","region","active"],project:t=>({name:t.name,environment:t.environment,accountName:t.accountName,region:t.region,active:t.active})},d={entity:"target",defaultFields:["name","status","environment","accountName","region"],extraFields:{accountId:{path:"accountId"}},aggregates:[]},u={entity:"target",defaultFields:["name","environment","accountName","region"],extraFields:{accountId:{path:"accountId"}},aggregates:[]},g={entity:"domains",defaultFields:["name","status"],extraFields:{path:{path:"path"},hasZoneFile:{path:"hasZoneFile"},hasInfrastructure:{path:"hasInfrastructure"}},aggregates:[{name:"total",compute:"count"}]},m={fields:["name","status"],project:t=>({name:t.name,status:t.status})},h={entity:"domain",defaultFields:["name","delegated"],extraFields:{nameservers:{path:"nameservers"}},aggregates:[]},A={entity:"export",defaultFields:["name","recordCount","zoneFilePath"],extraFields:{content:{path:"content",transform:"truncate"}},aggregates:[]},x={entity:"import",defaultFields:["name","hostedZoneId","recordCount","path"],extraFields:{},aggregates:[]},F={entity:"domain",defaultFields:["name","path"],extraFields:{},aggregates:[]},y={entity:"account",defaultFields:["status","region","outputPath"],extraFields:{warning:{path:"warning"}},aggregates:[]},E={entity:"organisation",defaultFields:["name","status","path"],extraFields:{email:{path:"email"},primaryRegion:{path:"primaryRegion"},security:{path:"security"},warning:{path:"warning"}},aggregates:[]},_={entity:"restore",defaultFields:["resourceType","recoveryPointArn","status"],extraFields:{iamRole:{path:"iamRole",transform:"truncate"},restoreJobArn:{path:"restoreJobArn",transform:"truncate"},consoleUrl:{path:"consoleUrl"}},aggregates:[]},C={entity:"import",defaultFields:["action","target","dryRun"],extraFields:{region:{path:"region"},discoveryMode:{path:"discoveryMode"}},aggregates:[{name:"resourceCount",compute:"count"}]},T={entity:"sync",defaultFields:["app","region","resourceCount"],extraFields:{awsAccountId:{path:"awsAccountId"},auditRole:{path:"hasAuditRole"}},aggregates:[{name:"resourceCount",compute:"count"}]};export{s as ADD_SCHEMA,e as CONNECT_SCHEMA,y as CREATE_ACCOUNT_SCHEMA,F as CREATE_DOMAIN_SCHEMA,E as CREATE_ORG_SCHEMA,A as DOMAIN_EXPORT_SCHEMA,x as DOMAIN_IMPORT_SCHEMA,g as DOMAIN_LIST_SCHEMA,m as DOMAIN_LIST_TABULAR,h as DOMAIN_VERIFY_SCHEMA,r as HISTORY_SCHEMA,i as HISTORY_TABULAR,C as IMPORT_SCHEMA,n as LIST_SCHEMA,o as LIST_TABULAR,a as LOGIN_SCHEMA,_ as RESTORE_SCHEMA,T as SYNC_SCHEMA,d as TARGET_GET_SCHEMA,l as TARGET_LIST_SCHEMA,p as TARGET_LIST_TABULAR,u as TARGET_SET_SCHEMA,c as TUNNEL_SCHEMA};

package/bin/assets/src/util/agent/schemas/secretsSchemas.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent output schemas for secrets commands.
+ */
+import type { AgentSchema, TabularSchema } from "./types.js";
+import type { SecretEntry } from "../../../services/index.js";
+export declare const SECRETS_LIST_SCHEMA: AgentSchema;
+export declare const SECRETS_LIST_TABULAR: TabularSchema<SecretEntry>;
+export declare const SECRETS_GET_SCHEMA: AgentSchema;
+export declare const SECRETS_SET_SCHEMA: AgentSchema;
+export declare const SECRETS_DELETE_SCHEMA: AgentSchema;
+export declare const SECRETS_IMPORT_SCHEMA: AgentSchema;
+export declare const SECRETS_EXPORT_SCHEMA: AgentSchema;
+export declare const SECRETS_EXEC_SCHEMA: AgentSchema;

package/bin/assets/src/util/agent/schemas/secretsSchemas.js

@@ -0,0 +1 @@
+const t={entity:"secrets",defaultFields:["name","lastModified"],extraFields:{version:{path:"version"},arn:{path:"arn"}},aggregates:[{name:"total",compute:"count"}]},a={fields:["name","lastModified"],project:e=>({name:e.name,lastModified:e.lastModified?.toISOString()??""})},s={entity:"secret",defaultFields:["name","value"],extraFields:{},aggregates:[]},r={entity:"secret",defaultFields:["name"],extraFields:{},aggregates:[]},i={entity:"secret",defaultFields:["name"],extraFields:{},aggregates:[]},o={entity:"import",defaultFields:["count"],extraFields:{},aggregates:[]},n={entity:"export",defaultFields:["format","content"],extraFields:{},aggregates:[]},d={entity:"exec",defaultFields:["exitCode"],extraFields:{},aggregates:[]};export{i as SECRETS_DELETE_SCHEMA,d as SECRETS_EXEC_SCHEMA,n as SECRETS_EXPORT_SCHEMA,s as SECRETS_GET_SCHEMA,o as SECRETS_IMPORT_SCHEMA,t as SECRETS_LIST_SCHEMA,a as SECRETS_LIST_TABULAR,r as SECRETS_SET_SCHEMA};

package/bin/assets/src/util/agent/schemas/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared types for agent output schemas. These describe the internal
+ * wiring between operation callbacks and the TOON output layer — they are
+ * author-controlled, not user input, so plain interfaces are used instead
+ * of Zod.
+ *
+ * Per-command schemas that consume these types land in Phase 3.
+ */
+import type { AgentErrorCode } from "../errorCodes.js";
+/**
+ * Describes how a single command's TOON output is assembled.
+ *
+ * - `entity` is the top-level TOON key (e.g. "apps", "deployment", "secret")
+ * - `defaultFields` are rendered without extra flags
+ * - `extraFields` require `--fields <name>` to appear
+ * - `aggregates` are pre-computed summaries rendered as sibling keys
+ */
+export interface AgentSchema {
+    readonly entity: string;
+    readonly defaultFields: readonly string[];
+    readonly extraFields: Readonly<Record<string, FieldSource>>;
+    readonly aggregates: readonly Aggregate[];
+}
+/**
+ * Describes where a field's value comes from on a source object.
+ *
+ * - `path` is a dot-path from the source root; defaults to the field name
+ *   when omitted
+ * - `transform` names a named transform applied after path resolution
+ */
+export interface FieldSource {
+    readonly path?: string;
+    readonly transform?: TransformName;
+}
+/**
+ * Closed union of named transforms. New transforms are added by widening
+ * this union and registering the implementation in the formatter.
+ */
+export type TransformName = "relativeTime" | "truncate" | "currency" | "mask";
+/**
+ * A pre-computed aggregate attached to a list's output. Rendered as a
+ * sibling TOON key.
+ */
+export type Aggregate = {
+    readonly name: string;
+    readonly compute: "count";
+} | {
+    readonly name: string;
+    readonly compute: "countWhere";
+    readonly field: string;
+    readonly value: string;
+} | {
+    readonly name: string;
+    readonly compute: "sum";
+    readonly field: string;
+};
+/**
+ * A structured error rendered in the TOON error block. `code` is a stable
+ * machine-readable string; `userActionRequired` tells the agent whether a
+ * human must intervene.
+ */
+export interface AgentError {
+    readonly message: string;
+    readonly code: AgentErrorCode;
+    readonly userActionRequired?: boolean;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * An action-required TOON block. Emitted when the agent needs to take a
+ * specific action (add a flag, perform SSO, pick an option) before the
+ * command can proceed.
+ */
+export interface ActionRequired {
+    readonly action: string;
+    readonly message: string;
+    readonly userActionRequired: boolean;
+    readonly choices?: readonly string[];
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A streaming event produced by long-running commands (deploy, destroy,
+ * build). Rendered as a TOON block separated from other blocks by the
+ * block separator.
+ */
+export interface StreamEvent {
+    readonly operation: string;
+    readonly field: string;
+    readonly value: unknown;
+}
+/**
+ * A tabular schema for rendering uniform arrays. The `project` function
+ * normalises each item to a flat row of primitives — this guarantees
+ * `@toon-format/toon`'s tabular encoding path is hit.
+ */
+export interface TabularSchema<T> {
+    readonly fields: readonly string[];
+    readonly project: (item: T) => Readonly<Record<string, string | number | boolean | null>>;
+}

package/bin/assets/src/util/agent/schemas/userSchemas.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent output schemas for user + token commands.
+ */
+import type { AgentSchema, TabularSchema } from "./types.js";
+import type { TokenSummary } from "../../../util/api/FjallApiClient.types.js";
+export declare const USER_LIST_SCHEMA: AgentSchema;
+export declare const USER_LIST_TABULAR: TabularSchema<{
+    username: string;
+    displayName: string;
+    userId: string;
+}>;
+export declare const USER_CREATE_SCHEMA: AgentSchema;
+export declare const USER_DESTROY_SCHEMA: AgentSchema;
+export declare const USER_MEMBERSHIP_SCHEMA: AgentSchema;
+export declare const TOKEN_LIST_SCHEMA: AgentSchema;
+export declare const TOKEN_LIST_TABULAR: TabularSchema<TokenSummary & {
+    status: string;
+}>;
+export declare const TOKEN_CREATE_SCHEMA: AgentSchema;
+export declare const TOKEN_SHOW_SCHEMA: AgentSchema;
+export declare const TOKEN_REVOKE_SCHEMA: AgentSchema;

package/bin/assets/src/util/agent/schemas/userSchemas.js

@@ -0,0 +1 @@
+const t={entity:"users",defaultFields:["username","displayName"],extraFields:{userId:{path:"userId"}},aggregates:[{name:"total",compute:"count"}]},s={fields:["username","displayName","userId"],project:e=>({username:e.username,displayName:e.displayName,userId:e.userId})},a={entity:"user",defaultFields:["username","userId"],extraFields:{},aggregates:[]},r={entity:"user",defaultFields:["username"],extraFields:{},aggregates:[]},o={entity:"membership",defaultFields:["username","groupname"],extraFields:{},aggregates:[]},n={entity:"tokens",defaultFields:["name","scopes","status","expiresAt"],extraFields:{id:{path:"id"},tokenPrefix:{path:"tokenPrefix"},lastUsedAt:{path:"lastUsedAt"},usageCount:{path:"usageCount"}},aggregates:[{name:"total",compute:"count"}]},d={fields:["name","scopes","status","expiresAt"],project:e=>({name:e.name,scopes:e.scopes.join(","),status:e.status,expiresAt:e.expiresAt??""})},u={entity:"token",defaultFields:["id","name","tokenPrefix"],extraFields:{},aggregates:[]},i={entity:"token",defaultFields:["id","name","tokenPrefix","scopes","status","expiresAt","createdAt","lastUsedAt","usageCount","deniedCount"],extraFields:{sourceTag:{path:"sourceTag"},revokedAt:{path:"revokedAt"},revokedReason:{path:"revokedReason"}},aggregates:[]},p={entity:"token",defaultFields:["id"],extraFields:{},aggregates:[]};export{u as TOKEN_CREATE_SCHEMA,n as TOKEN_LIST_SCHEMA,d as TOKEN_LIST_TABULAR,p as TOKEN_REVOKE_SCHEMA,i as TOKEN_SHOW_SCHEMA,a as USER_CREATE_SCHEMA,r as USER_DESTROY_SCHEMA,t as USER_LIST_SCHEMA,s as USER_LIST_TABULAR,o as USER_MEMBERSHIP_SCHEMA};

package/bin/assets/src/util/agent/sessionHooks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Session hook installer and uninstaller for AI agent tools.
+ *
+ * Manages hook entries in agent configuration files:
+ * - Claude Code: ~/.claude/settings.json (UserProjectConfig hook)
+ * - Codex: ~/.codex/hooks.json (pre-session hook)
+ *
+ * Respects opt-out sentinel (~/.fjall/hook-opt-out) and
+ * FJALL_DISABLE_HOOKS=1 environment variable.
+ */
+/**
+ * Check whether hook installation is disabled via environment variable
+ * or persistent opt-out sentinel.
+ */
+export declare function isHookInstallDisabled(): boolean;
+/**
+ * Check whether the opt-out sentinel exists.
+ */
+export declare function hasOptOutSentinel(): boolean;
+/**
+ * Write the persistent opt-out sentinel file.
+ */
+export declare function writeOptOutSentinel(): void;
+/**
+ * Remove the persistent opt-out sentinel file.
+ */
+export declare function removeOptOutSentinel(): void;
+interface InstallResult {
+    readonly installed: readonly string[];
+    readonly skipped: readonly string[];
+    readonly errors: readonly string[];
+}
+/**
+ * Install session hooks for all detected agent tools.
+ *
+ * Skips if opt-out sentinel exists or FJALL_DISABLE_HOOKS=1, unless
+ * `forceInstall` is true (which also removes the sentinel).
+ */
+export declare function installHooks(options?: {
+    forceInstall?: boolean;
+}): InstallResult;
+/**
+ * Uninstall session hooks from all detected agent tools and write
+ * the opt-out sentinel.
+ */
+export declare function uninstallHooks(): InstallResult;
+export {};

package/bin/assets/src/util/agent/sessionHooks.js

@@ -0,0 +1,6 @@
+import{existsSync as l,mkdirSync as h,readFileSync as f,unlinkSync as m,writeFileSync as c}from"node:fs";import{join as i}from"node:path";import{homedir as a}from"node:os";import{logger as k}from"../logger/index.js";const p=i(a(),".fjall"),d=i(p,"hook-opt-out"),g="fjall status --agent --budget minimal",u="fjall-agent-session-hook";function y(){return process.env.FJALL_DISABLE_HOOKS==="1"?!0:l(d)}function E(){return l(d)}function C(){h(p,{recursive:!0}),c(d,`opted-out-at: ${new Date().toISOString()}
+`)}function S(){try{m(d)}catch(s){k.debug("SessionHooks","removeOptOutSentinel failed",{error:s instanceof Error?s.message:String(s)})}}function I(s){const e=[],r=[],o=[];if(!s?.forceInstall&&y())return k.debug("SessionHooks","Hook installation disabled (opt-out or env)"),{installed:e,skipped:["all (opt-out active)"],errors:o};s?.forceInstall&&S();const t=x();t.status==="installed"?e.push("Claude Code (~/.claude/settings.json)"):t.status==="skipped"?r.push(`Claude Code: ${t.reason}`):o.push(`Claude Code: ${t.reason}`);const n=O();return n.status==="installed"?e.push("Codex (~/.codex/hooks.json)"):n.status==="skipped"?r.push(`Codex: ${n.reason}`):o.push(`Codex: ${n.reason}`),{installed:e,skipped:r,errors:o}}function N(){const s=[],e=[],r=[],o=j();o.removed?s.push("Claude Code (~/.claude/settings.json)"):e.push(`Claude Code: ${o.reason}`);const t=v();return t.removed?s.push("Codex (~/.codex/hooks.json)"):e.push(`Codex: ${t.reason}`),C(),{installed:s,skipped:e,errors:r}}function x(){const s=i(a(),".claude","settings.json");try{let e={};if(l(s)){const t=f(s,"utf-8"),n=JSON.parse(t);e=typeof n=="object"&&n!==null&&!Array.isArray(n)?n:{}}else h(i(a(),".claude"),{recursive:!0});e.hooks||(e.hooks={}),Array.isArray(e.hooks.UserProjectConfig)||(e.hooks.UserProjectConfig=[]);const r=e.hooks.UserProjectConfig.findIndex(t=>t.marker===u),o={type:"command",command:g,marker:u};return r>=0?e.hooks.UserProjectConfig[r]=o:e.hooks.UserProjectConfig.push(o),c(s,JSON.stringify(e,null,2)+`
+`),{status:"installed"}}catch(e){return{status:"error",reason:e instanceof Error?e.message:String(e)}}}function j(){const s=i(a(),".claude","settings.json");try{if(!l(s))return{removed:!1,reason:"settings file not found"};const e=f(s,"utf-8"),r=JSON.parse(e),o=typeof r=="object"&&r!==null&&!Array.isArray(r)?r:{};if(!o.hooks?.UserProjectConfig)return{removed:!1,reason:"no hooks configured"};const t=o.hooks.UserProjectConfig.length;return o.hooks.UserProjectConfig=o.hooks.UserProjectConfig.filter(n=>n.marker!==u),o.hooks.UserProjectConfig.length===t?{removed:!1,reason:"hook not found"}:(c(s,JSON.stringify(o,null,2)+`
+`),{removed:!0,reason:"removed"})}catch(e){return{removed:!1,reason:e instanceof Error?e.message:String(e)}}}function O(){const s=i(a(),".codex","hooks.json");try{let e={};if(l(s)){const t=f(s,"utf-8"),n=JSON.parse(t);e=typeof n=="object"&&n!==null&&!Array.isArray(n)?n:{}}else h(i(a(),".codex"),{recursive:!0});Array.isArray(e.hooks)||(e.hooks=[]);const r=e.hooks.findIndex(t=>t.marker===u),o={type:"command",event:"pre-session",command:g,marker:u};return r>=0?e.hooks[r]=o:e.hooks.push(o),c(s,JSON.stringify(e,null,2)+`
+`),{status:"installed"}}catch(e){return{status:"error",reason:e instanceof Error?e.message:String(e)}}}function v(){const s=i(a(),".codex","hooks.json");try{if(!l(s))return{removed:!1,reason:"hooks file not found"};const e=f(s,"utf-8"),r=JSON.parse(e),o=typeof r=="object"&&r!==null&&!Array.isArray(r)?r:{};if(!Array.isArray(o.hooks))return{removed:!1,reason:"no hooks configured"};const t=o.hooks.length;return o.hooks=o.hooks.filter(n=>n.marker!==u),o.hooks.length===t?{removed:!1,reason:"hook not found"}:(c(s,JSON.stringify(o,null,2)+`
+`),{removed:!0,reason:"removed"})}catch(e){return{removed:!1,reason:e instanceof Error?e.message:String(e)}}}export{E as hasOptOutSentinel,I as installHooks,y as isHookInstallDisabled,S as removeOptOutSentinel,N as uninstallHooks,C as writeOptOutSentinel};

package/bin/assets/src/util/agent/streaming.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Streaming TOON adapter for long-running AXI operations (deploy, destroy,
+ * build). Wraps AgentOutputWriter to emit multi-block streaming output
+ * with phase progress, resource updates, and a terminal result block.
+ *
+ * The callback mapping itself lives in agentCallbacks.ts and is re-exported
+ * here for convenience — callers that need both streaming and callbacks
+ * import from a single module.
+ */
+import { AgentOutputWriter, type AgentOutputWriterOptions } from "./agentOutput.js";
+import type { SuggestionContext } from "./suggestions.js";
+export { createAgentOutput, type AgentCallbacksOutput } from "./agentCallbacks.js";
+export interface ResourceStatus {
+    readonly name: string;
+    readonly type: string;
+    readonly status: string;
+}
+/**
+ * High-level streaming writer for deploy/destroy/build operations.
+ *
+ * Each method emits one or more TOON blocks via the underlying
+ * AgentOutputWriter, separated by `---` block separators. The sequence
+ * is: zero or more phase/resource blocks, then a single terminal result.
+ */
+export declare class StreamingToonWriter {
+    private readonly writer;
+    private readonly operation;
+    private blockEmitted;
+    constructor(options: AgentOutputWriterOptions & {
+        operation: string;
+    });
+    /**
+     * Emit a phase-progress block. Separates from the previous block if one
+     * has already been written.
+     */
+    writePhase(phase: string, step: string, progress: number): void;
+    /**
+     * Emit a resource-status block listing one or more resources and their
+     * current deployment status.
+     */
+    writeResources(resources: readonly ResourceStatus[]): void;
+    /**
+     * Emit the terminal result block. This is the final block in the stream
+     * and includes contextual help suggestions. No further blocks should be
+     * written after this.
+     */
+    writeTerminalResult(result: Record<string, unknown>, suggestionContext: SuggestionContext): void;
+    /** Expose the underlying writer for callers that need direct access. */
+    getWriter(): AgentOutputWriter;
+    private emitSeparatorIfNeeded;
+}

package/bin/assets/src/util/agent/streaming.js

@@ -0,0 +1 @@
+import{AgentOutputWriter as i}from"./agentOutput.js";import{createAgentOutput as d}from"./agentCallbacks.js";class a{writer;operation;blockEmitted=!1;constructor(e){const{operation:t,...r}=e;this.writer=new i(r),this.operation=t}writePhase(e,t,r){this.emitSeparatorIfNeeded(),this.writer.renderEvent({operation:this.operation,field:"phase",value:{phase:e,step:t,progress:r}}),this.blockEmitted=!0}writeResources(e){this.emitSeparatorIfNeeded(),this.writer.renderEvent({operation:this.operation,field:"resources",value:e}),this.blockEmitted=!0}writeTerminalResult(e,t){this.emitSeparatorIfNeeded(),this.writer.renderResult(e,{suggestionContext:t})}getWriter(){return this.writer}emitSeparatorIfNeeded(){this.blockEmitted&&this.writer.emitEventSeparator()}}export{a as StreamingToonWriter,d as createAgentOutput};

package/bin/assets/src/util/agent/suggestionEntries/coreEntries.d.ts

@@ -0,0 +1,2 @@
+import { type SuggestionEntry } from "./types.js";
+export declare const CORE_ENTRIES: readonly SuggestionEntry[];

package/bin/assets/src/util/agent/suggestionEntries/coreEntries.js

@@ -0,0 +1 @@
+import{matchOutcome as a}from"./types.js";const t=[{command:"home",match:a.success,templates:["Run `fjall apps describe <name>` to see app details","Run `fjall deploy <name>` to deploy","Run `fjall status <name>` to check a specific app"]},{command:"home",match:a.empty,templates:['Run `fjall apps create --name "<name>"` to create your first app',"Run `fjall connect` to connect an AWS account"]},{command:"apps list",match:a.success,templates:["Run `fjall apps describe <name>` to see app details","Run `fjall deploy <name>` to deploy",'Run `fjall apps create --name "<name>"` to create a new app']},{command:"apps list",match:a.empty,templates:['Run `fjall apps create --name "<name>"` to create your first app',"Run `fjall connect` to connect an AWS account first"]},{command:"apps describe",match:a.success,templates:["Run `fjall deploy <app>` to deploy","Run `fjall secrets list --app <app>` to list secrets","Run `fjall status <app>` to check health"]},{command:"apps create",match:a.success,templates:["Run `fjall deploy <app>` to deploy your new app","Run `fjall secrets set --app <app> --key DB_URL --value <url>` to configure secrets"]},{command:"status",match:a.success,templates:["Run `fjall deploy <app>` to deploy","Run `fjall apps describe <app>` for details"]},{command:"deploy",match:a.success,templates:["Run `fjall status <app>` to check health","Run `fjall apps describe <app>` for full details"]},{command:"deploy",match:a.error,templates:["Run `fjall deploy <app>` to retry","Run `fjall status <app>` to check current state"]},{command:"destroy",match:a.success,templates:["Run `fjall list` to see remaining resources","Run `fjall apps list` to see remaining apps"]},{command:"destroy",match:a.error,templates:["Run `fjall destroy <app> --skip-confirmation` to force destroy","Run `fjall status <app>` to check current state"]},{command:"build",match:a.success,templates:["Run `fjall deploy <app> --skip-build` to deploy the built image","Run `fjall status <app>` to check health"]},{command:"connect",match:a.success,templates:["Run `fjall deploy account` or `fjall deploy organisation` to deploy infrastructure",'Run `fjall apps create --name "<name>"` to create an app']},{command:"login",match:a.success,templates:["Run `fjall apps list` to see your applications","Run `fjall connect` to connect an AWS account"]},{command:"list",match:a.success,templates:["Run `fjall apps describe <name>` for app details","Run `fjall deploy <name>` to deploy"]},{command:"add",match:a.success,templates:["Run `fjall deploy <app>` to deploy the change","Run `fjall apps describe <app>` to see updated resources"]},{command:"tunnel",match:a.success,templates:["Run `fjall tunnel <app> --background` to run in the background"]}];export{t as CORE_ENTRIES};

package/bin/assets/src/util/agent/suggestionEntries/identityEntries.d.ts

@@ -0,0 +1,2 @@
+import { type SuggestionEntry } from "./types.js";
+export declare const IDENTITY_ENTRIES: readonly SuggestionEntry[];

package/bin/assets/src/util/agent/suggestionEntries/identityEntries.js

@@ -0,0 +1 @@
+import{matchOutcome as e}from"./types.js";const a=[{command:"user list",match:e.success,templates:["Run `fjall user create --email <email> --first-name <name> --last-name <name>` to add a user","Run `fjall user associate <username> <group>` to assign a group"]},{command:"user list",match:e.empty,templates:["Run `fjall user create --email <email> --first-name <name> --last-name <name>` to create a user"]},{command:"user create",match:e.success,templates:["Run `fjall user associate <username> <group>` to assign a group","Run `fjall user list` to see all users"]},{command:"user destroy",match:e.success,templates:["Run `fjall user list` to see remaining users"]},{command:"user associate",match:e.success,templates:["Run `fjall user list` to verify group membership"]},{command:"user dissociate",match:e.success,templates:["Run `fjall user list` to verify group membership"]},{command:"user token create",match:e.success,templates:["Run `fjall user token list` to see all tokens","Save the token now \u2014 it cannot be retrieved again"]},{command:"user token list",match:e.success,templates:["Run `fjall user token create --name <name> --scope <scope> --expires <duration>` to create a token","Run `fjall user token revoke <id>` to revoke a token"]},{command:"user token show",match:e.success,templates:["Run `fjall user token revoke <id>` to revoke this token","Run `fjall user token list` to see all tokens"]},{command:"user token revoke",match:e.success,templates:["Run `fjall user token list` to see remaining tokens"]},{command:"target list",match:e.success,templates:["Run `fjall target set <name>` to change active target","Run `fjall deploy <app>` to deploy to the active target","Run `fjall apps list` to see applications"]},{command:"target list",match:e.empty,templates:["Run `fjall connect` to connect an AWS account","Run `fjall login` to authenticate if not logged in"]},{command:"target get",match:e.success,templates:["Run `fjall target set <name>` to change active target","Run `fjall target list` to see all targets"]},{command:"target get",match:e.empty,templates:["Run `fjall target set <name>` to set a target","Run `fjall target list` to see available targets"]},{command:"target set",match:e.success,templates:["Run `fjall deploy <app>` to deploy to this target","Run `fjall target get` to verify the active target"]},{command:"target set",match:e.errorWithCode("NOT_FOUND"),templates:["Run `fjall target list` to see available targets","Run `fjall connect` to connect an AWS account if none available"]}];export{a as IDENTITY_ENTRIES};

package/bin/assets/src/util/agent/suggestionEntries/index.d.ts

@@ -0,0 +1,3 @@
+import { type SuggestionEntry } from "./types.js";
+export declare const SUGGESTION_TABLE: readonly SuggestionEntry[];
+export type { SuggestionContext, SuggestionEntry } from "./types.js";

package/bin/assets/src/util/agent/suggestionEntries/index.js

@@ -0,0 +1 @@
+import{matchOutcome as o}from"./types.js";import{CORE_ENTRIES as m}from"./coreEntries.js";import{SECRETS_ENTRIES as r}from"./secretsEntries.js";import{IDENTITY_ENTRIES as E}from"./identityEntries.js";import{INFRA_ENTRIES as t}from"./infraEntries.js";import{OBSERVABILITY_ENTRIES as T}from"./observabilityEntries.js";const I={command:"*",match:o.error,templates:["Run `fjall <command> --help` for usage information"]},i=[...m,...r,...E,...t,...T,I];export{i as SUGGESTION_TABLE};

package/bin/assets/src/util/agent/suggestionEntries/infraEntries.d.ts

@@ -0,0 +1,2 @@
+import { type SuggestionEntry } from "./types.js";
+export declare const INFRA_ENTRIES: readonly SuggestionEntry[];

package/bin/assets/src/util/agent/suggestionEntries/infraEntries.js

@@ -0,0 +1 @@
+import{matchOutcome as e}from"./types.js";const a=[{command:"domain list",match:e.success,templates:["Run `fjall domain verify <name>` to check DNS delegation","Run `fjall domain export <name>` to export zone file","Run `fjall create domain --name <name>` to create a new domain"]},{command:"domain list",match:e.empty,templates:['Run `fjall create domain --name "<name>"` to create a domain',"Run `fjall domain import <name>` to import from Route53"]},{command:"domain verify",match:e.success,templates:["Run `fjall domain export <name>` to export zone file","Run `fjall deploy <name>` to deploy domain infrastructure"]},{command:"domain verify",match:e.error,templates:["Run `fjall domain verify <name>` to retry","Run `fjall domain list` to see existing domains"]},{command:"domain export",match:e.success,templates:["Run `fjall domain verify <name>` to check delegation","Run `fjall domain import <name>` to re-import from Route53"]},{command:"domain import",match:e.success,templates:["Run `fjall domain verify <name>` to check delegation","Run `fjall domain export <name>` to see the zone file","Run `fjall deploy <name>` to deploy domain infrastructure"]},{command:"domain import",match:e.error,templates:["Run `fjall domain import --hosted-zone-id <id>` to import by zone ID","Run `fjall domain list` to see existing domains"]},{command:"create domain",match:e.success,templates:["Run `fjall domain verify <name>` to check DNS delegation","Run `fjall domain export <name>` to export zone records","Run `fjall deploy <name>` to deploy the domain"]},{command:"create domain",match:e.error,templates:["Run `fjall domain list` to see existing domains",'Run `fjall create domain --name "<name>"` to retry with a different name']},{command:"create account",match:e.success,templates:["Run `fjall connect --environment production` to link your AWS account","Run `fjall deploy account` to deploy account infrastructure (after connecting)"]},{command:"create account",match:e.error,templates:["Run `fjall create account --primary-region <region>` to retry","Run `fjall create account --help` for usage information"]},{command:"create org",match:e.success,templates:["Run `fjall connect --environment production` to link your AWS account","Run `fjall deploy organisation` to deploy all infrastructure (after connecting)"]},{command:"create org",match:e.error,templates:['Run `fjall create org --name "<name>" --email "<email>"` to retry',"Run `fjall create org --help` for all options"]},{command:"restore",match:e.successDryRun,templates:["Run `fjall restore <resourceType> --recovery-point <recoveryPointArn> --yes` to initiate restore","Run `fjall apps list` to see existing applications"]},{command:"restore",match:e.success,templates:["Open the AWS Console URL above to monitor restore progress","Run `fjall import` to import the restored resource after completion"]},{command:"restore",match:e.errorWithCode("NOT_FOUND"),templates:["Verify the recovery point ARN is correct and exists in the current region","Run `fjall restore <resourceType> --recovery-point <arn>` to retry"]},{command:"restore",match:e.errorWithCode("FORBIDDEN"),templates:["Ensure the IAM role has backup:StartRestoreJob and iam:PassRole permissions","Run `fjall restore` interactively to configure with guided setup"]},{command:"import",match:e.successDryRun,templates:["Run `fjall import --app <app> --resource-id <resourceId> --yes` to import a specific resource","Run `fjall import --app <app> --yes` to import all discovered resources"]},{command:"import",match:e.success,templates:["Run `fjall deploy <app>` to deploy with the imported resource","Run `fjall apps describe <app>` to see updated resources"]},{command:"import",match:e.errorWithCode("NOT_FOUND"),templates:['Run `fjall apps create --name "<app>"` to create the application',"Run `fjall apps list` to see existing applications"]},{command:"import",match:e.errorWithCode("VALIDATION_ERROR"),templates:["Run `fjall import --app <app> --resource-id <resourceId>` to import a specific resource","Run `fjall import --app <app> --resource-id <resourceId> --yes` to import immediately"]},{command:"sync",match:e.success,templates:["Run `fjall status <app>` to check health","Run `fjall deploy <app>` to deploy latest changes"]},{command:"sync",match:e.error,templates:["Run `fjall sync <app>` to retry","Run `fjall status <app>` to check current state"]},{command:"aws exec",match:e.success,templates:["Run `fjall aws exec -- <command>` to run another AWS CLI command","Run `fjall status` to check application health"]},{command:"aws exec",match:e.error,templates:["Run `fjall connect` to configure an AWS account","Run `fjall aws exec --help` for usage information"]}];export{a as INFRA_ENTRIES};

package/bin/assets/src/util/agent/suggestionEntries/observabilityEntries.d.ts

@@ -0,0 +1,2 @@
+import { type SuggestionEntry } from "./types.js";
+export declare const OBSERVABILITY_ENTRIES: readonly SuggestionEntry[];

package/bin/assets/src/util/agent/suggestionEntries/observabilityEntries.js

@@ -0,0 +1 @@
+import{matchOutcome as e}from"./types.js";const t=[{command:"costs show",match:e.success,templates:["Run `fjall costs --mode forecast` to see forecasted spend","Run `fjall costs --mode breakdown` to see service-level breakdown"]},{command:"costs show",match:e.error,templates:["Run `fjall costs --app <app>` to filter by application","Run `fjall costs --help` for usage information"]},{command:"metrics show",match:e.success,templates:["Run `fjall metrics --mode latency` to see latency percentiles","Run `fjall metrics --mode errors` to see error trends"]},{command:"metrics show",match:e.error,templates:["Run `fjall metrics --app <app>` to filter by application","Run `fjall metrics --help` for usage information"]},{command:"compliance fix",match:e.success,templates:["Run `fjall compliance --issue-id <id>` to get details for a specific issue","Run `fjall deploy <app>` to apply remediation changes"]},{command:"compliance fix",match:e.error,templates:["Run `fjall compliance --domain <domain>` to specify compliance domain","Run `fjall compliance --help` for usage information"]},{command:"deploy diff",match:e.success,templates:["Run `fjall deploy logs --deployment-id <id>` to analyse deployment logs","Run `fjall status <app>` to check current deployment health"]},{command:"deploy diff",match:e.error,templates:["Run `fjall list deployments` to see recent deployment IDs","Run `fjall deploy diff --help` for usage information"]},{command:"deploy logs",match:e.success,templates:["Run `fjall deploy diff <idA> <idB>` to compare two deployments","Run `fjall status <app>` to check current deployment health"]},{command:"deploy logs",match:e.error,templates:["Run `fjall deploy logs --deployment-id <id>` with a valid deployment ID","Run `fjall list deployments` to find a deployment ID"]}];export{t as OBSERVABILITY_ENTRIES};

package/bin/assets/src/util/agent/suggestionEntries/secretsEntries.d.ts

@@ -0,0 +1,2 @@
+import { type SuggestionEntry } from "./types.js";
+export declare const SECRETS_ENTRIES: readonly SuggestionEntry[];

package/bin/assets/src/util/agent/suggestionEntries/secretsEntries.js

@@ -0,0 +1 @@
+import{matchOutcome as e}from"./types.js";const t=[{command:"secrets list",match:e.success,templates:['Run `fjall secrets set --app <app> --key "<key>" --value "<value>"` to set a secret',"Run `fjall deploy <app>` to apply changes"]},{command:"secrets list",match:e.empty,templates:['Run `fjall secrets set --app <app> --key "<key>" --value "<value>"` to add a secret',"Run `fjall secrets import --app <app> <file>` to bulk import"]},{command:"secrets get",match:e.success,templates:['Run `fjall secrets set --app <app> --key "<key>" --value "<value>"` to update',"Run `fjall secrets list --app <app>` to see all secrets"]},{command:"secrets set",match:e.success,templates:["Run `fjall deploy <app>` to apply the change","Run `fjall secrets list --app <app>` to verify"]},{command:"secrets delete",match:e.success,templates:["Run `fjall deploy <app>` to apply the change","Run `fjall secrets list --app <app>` to verify"]},{command:"secrets import",match:e.success,templates:["Run `fjall deploy <app>` to apply changes","Run `fjall secrets list --app <app>` to verify"]},{command:"secrets export",match:e.success,templates:["Run `fjall secrets list --app <app>` to see all secret names","Run `fjall secrets import --app <app> <file>` to restore"]},{command:"secrets exec",match:e.success,templates:["Run `fjall secrets list --app <app>` to see available secrets"]}];export{t as SECRETS_ENTRIES};

package/bin/assets/src/util/agent/suggestionEntries/types.d.ts

@@ -0,0 +1,17 @@
+export interface SuggestionContext {
+    readonly command: string;
+    readonly outcome?: "success" | "error" | "empty";
+    readonly [key: string]: string | undefined;
+}
+export interface SuggestionEntry {
+    readonly command: string;
+    readonly match: (ctx: SuggestionContext) => boolean;
+    readonly templates: readonly string[];
+}
+export declare const matchOutcome: {
+    readonly success: (ctx: SuggestionContext) => boolean;
+    readonly error: (ctx: SuggestionContext) => boolean;
+    readonly empty: (ctx: SuggestionContext) => boolean;
+    readonly successDryRun: (ctx: SuggestionContext) => boolean;
+    readonly errorWithCode: (code: string) => (ctx: SuggestionContext) => boolean;
+};

package/bin/assets/src/util/agent/suggestionEntries/types.js

@@ -0,0 +1 @@
+const r={success:e=>e.outcome==="success",error:e=>e.outcome==="error",empty:e=>e.outcome==="empty",successDryRun:e=>e.outcome==="success"&&e.dryRun==="true",errorWithCode:e=>o=>o.outcome==="error"&&o.errorCode===e};export{r as matchOutcome};

package/bin/assets/src/util/agent/suggestions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Contextual suggestion resolver for AXI agent output. Generates `help[]`
+ * lines that appear after every command output, guiding agents to their
+ * next action.
+ *
+ * Entry tables are grouped by domain in `./suggestionEntries/`.
+ */
+import type { SuggestionContext } from "./suggestionEntries/types.js";
+export type { SuggestionContext } from "./suggestionEntries/types.js";
+/**
+ * Shell-escape a value for embedding in suggestion text.
+ *
+ * Suggestions are intended to be safe for an agent to copy-paste into a
+ * POSIX shell. Any value containing shell-active characters is wrapped in
+ * single quotes with embedded single quotes safely terminated.
+ */
+declare function shellEscape(value: string): string;
+/**
+ * Resolves contextual suggestions for agent output. Matches the current
+ * command and context against the suggestion table, interpolates
+ * placeholders, and preserves flags from the original invocation.
+ */
+export declare class SuggestionResolver {
+    private readonly command;
+    private readonly flags;
+    constructor(command: string, flags: Readonly<Record<string, string>>);
+    resolve(context: SuggestionContext): string[];
+    private interpolate;
+}
+export { shellEscape as _shellEscapeForTesting };

package/bin/assets/src/util/agent/suggestions.js

@@ -0,0 +1 @@
+import{SUGGESTION_TABLE as i}from"./suggestionEntries/index.js";const l=["app","environment","region","profile","target"];function a(s){return/[^\w@%+=:,./-]/.test(s)?`'${s.replace(/'/g,"'\\''")}'`:s}class f{command;flags;constructor(t,n){this.command=t,this.flags=n}resolve(t){const n=i.find(e=>(e.command===this.command||e.command==="*")&&e.match(t));return n===void 0?[]:n.templates.map(e=>this.interpolate(e,t))}interpolate(t,n){let e=t.replace(/<(\w+)>/g,(o,r)=>n[r]??`<${r}>`);for(const o of l){const r=this.flags[o];r!==void 0&&!e.includes(`--${o}`)&&(e+=` --${o} ${a(r)}`)}return e}}export{f as SuggestionResolver,a as _shellEscapeForTesting};

package/bin/assets/src/util/agent/tokenScopes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Maps each CLI command surface to the scoped-token scope(s) required to
+ * execute it. Used by the agent output layer to emit a structured
+ * `scope_required` error when a token lacks permissions, rather than a
+ * generic 403.
+ *
+ * `TokenScope` / `SCOPE_VALUES` are imported from `@fjall/util` so the
+ * webapp's `/api/tokens` schemas and the CLI's command-scope lookup
+ * share a single source of truth (closes 2026-04-28 review H5).
+ */
+import { type TokenScope } from "@fjall/util";
+export { type TokenScope };
+/**
+ * Command surface → minimum required scope(s). The first scope in the
+ * array is the primary; additional entries are alternatives that also
+ * grant access (e.g. `secrets:write` implies `secrets:read` at the
+ * middleware level, but we list the exact scope the command needs).
+ */
+export declare const COMMAND_SCOPES: Readonly<Record<string, readonly TokenScope[]>>;
+/**
+ * Look up the required scope(s) for a command. Returns `undefined` for
+ * commands not in the map (e.g. future commands not yet wired).
+ */
+export declare function getRequiredScopes(command: string): readonly TokenScope[] | undefined;