akm-cli 0.9.2-alpha.4 → 0.9.2

package/schemas/akm-task.json

@@ -1,10 +1,10 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://itlackey.github.io/akm/schemas/akm-task.json",
-  "title": "AKM Task v3",
-  "description": "Strict task-v3 source document. Exactly one executable selector and exactly one scheduling source are required. GitHub action refs are recognized source syntax but are not executed by AKM 0.9.2.",
+  "title": "AKM Task source v4",
+  "description": "Task source v4: typed inputs:, a single bounded output: schema, and OPTIONAL scheduling — a document with no schedule: is valid, runnable manually, composable, and is skipped (not rejected) by `akm task sync`. The akm: options bag and the on: trigger block from task v3 are gone (their members are top-level); there is no github-action uses: target; with: is legal only alongside uses: akm/command (use inputs: everywhere else for typed parameters), and output: is legal only on a command target (uses: commands/<ref> or uses: akm/command) — the only kinds whose runtime enforces it. task-v2 and task-v3 sources are converted to this schema by `akm migrate apply` — this document publishes only the version: 4 shape a task source parses to today.",
   "x-akm-runtimeConstraints": {
-    "authoritativeParser": "src/tasks/source-v3.ts",
+    "authoritativeParser": "src/tasks/source/task-source-v4.ts",
     "maxSourceUtf8Bytes": 1048576,
     "maxStringUtf8Bytes": 262144,
     "maxJsonDepth": 64,
@@ -16,17 +16,30 @@
   "required": ["version"],
   "additionalProperties": false,
   "properties": {
-    "version": { "const": 3 },
+    "version": { "const": 4 },
     "name": { "type": "string", "maxLength": 262144 },
+    "description": { "type": "string", "maxLength": 262144 },
+    "when_to_use": { "type": "string", "maxLength": 262144 },
+    "tags": {
+      "type": "array",
+      "maxItems": 1024,
+      "items": { "type": "string", "minLength": 1, "maxLength": 262144 }
+    },
+    "inputs": {
+      "type": "object",
+      "maxProperties": 128,
+      "propertyNames": { "$ref": "#/definitions/taskInputName" },
+      "additionalProperties": { "$ref": "#/definitions/inputDeclaration" }
+    },
+    "output": { "$ref": "#/definitions/outputSchemaDefinition" },
     "uses": {
       "oneOf": [
         { "const": "akm/command" },
-        { "$ref": "#/definitions/akmExecutableRef" },
-        { "$ref": "#/definitions/githubActionRef" }
+        { "$ref": "#/definitions/akmExecutableRef" }
       ]
     },
     "run": { "$ref": "#/definitions/nonemptyLiteral" },
-    "with": { "$ref": "#/definitions/jsonObject" },
+    "with": { "$ref": "#/definitions/builtinCommandWith" },
     "env": {
       "type": "object",
       "maxProperties": 256,
@@ -46,90 +59,53 @@
       "maxLength": 262144,
       "pattern": "^(?![\\\\/])(?![A-Za-z]:[\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?!.*[\\\\/]{2})(?!.*[\\\\/]$)[^\\u0000]+$"
     },
-    "akm": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "schedule": { "$ref": "#/definitions/nonemptyLiteral" },
-        "enabled": { "type": "boolean" },
-        "description": { "type": "string", "maxLength": 262144 },
-        "when_to_use": { "type": "string", "maxLength": 262144 },
-        "tags": {
-          "type": "array",
-          "maxItems": 1024,
-          "items": { "type": "string", "minLength": 1, "maxLength": 262144 }
-        },
-        "agent": { "$ref": "#/definitions/nullableSelector" },
-        "engine": { "$ref": "#/definitions/nullableSelector" },
-        "model": { "$ref": "#/definitions/nullableSelector" },
-        "inference": {
-          "oneOf": [
-            { "$ref": "#/definitions/jsonObject" },
-            { "type": "null" }
-          ]
-        },
-        "outputSchema": {
-          "description": "A JSON Schema accepted by AKM's bounded execution-schema subset, or null. Runtime byte, depth, and node limits are declared by x-akm-runtimeConstraints.",
-          "oneOf": [
-            { "$ref": "#/definitions/outputSchemaDefinition" },
-            { "type": "null" }
-          ]
-        },
-        "tools": {
-          "oneOf": [
-            { "type": "string", "maxLength": 262144 },
-            {
-              "type": "array",
-              "maxItems": 1024,
-              "items": { "type": "string", "maxLength": 262144 }
-            },
-            { "$ref": "#/definitions/jsonObject" },
-            { "type": "null" }
-          ]
-        },
-        "timeout": {
-          "oneOf": [
-            { "type": "integer", "minimum": 0, "maximum": 2147483647 },
-            { "type": "string", "pattern": "^\\d+[mMhHdD]$" },
-            { "type": "null" }
-          ]
-        },
-        "redact": {
-          "type": "array",
-          "maxItems": 32,
-          "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
-        },
-        "maxSteps": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
-        "maxRetries": { "type": "integer", "minimum": 0, "maximum": 100 }
-      }
-    },
-    "on": {
-      "type": "object",
-      "minProperties": 1,
-      "additionalProperties": false,
-      "properties": {
-        "schedule": {
+    "schedule": {
+      "oneOf": [
+        { "$ref": "#/definitions/nonemptyLiteral" },
+        {
           "type": "array",
           "minItems": 1,
           "maxItems": 64,
-          "items": {
-            "type": "object",
-            "required": ["cron"],
-            "additionalProperties": false,
-            "properties": {
-              "cron": { "$ref": "#/definitions/nonemptyLiteral" }
-            }
-          }
-        },
-        "workflow_dispatch": {
-          "oneOf": [
-            { "type": "null" },
-            { "type": "object", "maxProperties": 0, "additionalProperties": false }
-          ]
+          "items": { "$ref": "#/definitions/taskSourceV4ScheduleEntry" }
         }
-      }
-    }
+      ]
+    },
+    "agent": { "$ref": "#/definitions/nullableSelector" },
+    "engine": { "$ref": "#/definitions/nullableSelector" },
+    "model": { "$ref": "#/definitions/nullableSelector" },
+    "inference": {
+      "oneOf": [
+        { "$ref": "#/definitions/jsonObject" },
+        { "type": "null" }
+      ]
+    },
+    "tools": {
+      "oneOf": [
+        { "type": "string", "maxLength": 262144 },
+        {
+          "type": "array",
+          "maxItems": 1024,
+          "items": { "type": "string", "maxLength": 262144 }
+        },
+        { "$ref": "#/definitions/jsonObject" },
+        { "type": "null" }
+      ]
+    },
+    "timeout": {
+      "oneOf": [
+        { "type": "integer", "minimum": 0, "maximum": 2147483647 },
+        { "type": "string", "pattern": "^\\d+[mMhHdD]$" },
+        { "type": "null" }
+      ]
+    },
+    "redact": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
+    },
+    "maxSteps": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+    "maxRetries": { "type": "integer", "minimum": 0, "maximum": 100 }
   },
   "oneOf": [
     {
@@ -148,54 +124,37 @@
       }
     },
     {
-      "description": "A canonical AKM executable ref or GitHub action ref.",
+      "description": "A canonical AKM executable ref (commands/, scripts/, or workflows/). No with: here — declare typed parameters with inputs: instead. output: is legal only on the commands/ arm: a scripts/ or workflows/ execution consumes no output schema, so an authored one would be a silently unenforced contract (src/tasks/source/task-source-v4.ts's targetConsumesOutputSchema).",
       "required": ["uses"],
       "properties": {
-        "uses": {
-          "oneOf": [
-            { "$ref": "#/definitions/akmExecutableRef" },
-            { "$ref": "#/definitions/githubActionRef" }
-          ]
-        }
+        "uses": { "$ref": "#/definitions/akmExecutableRef" }
       },
       "not": {
         "anyOf": [
           { "required": ["run"] },
+          { "required": ["with"] },
           { "required": ["shell"] },
           { "required": ["working-directory"] }
         ]
-      }
+      },
+      "if": {
+        "required": ["uses"],
+        "properties": { "uses": { "$ref": "#/definitions/akmCommandRef" } }
+      },
+      "else": { "not": { "required": ["output"] } }
     },
     {
-      "description": "One exact host-shell string.",
+      "description": "One exact host-shell string. No output: here — a run: execution decides status from its exit code alone and never enforces an output schema.",
       "required": ["run"],
       "not": {
         "anyOf": [
           { "required": ["uses"] },
-          { "required": ["with"] }
+          { "required": ["with"] },
+          { "required": ["output"] }
         ]
       }
     }
   ],
-  "allOf": [
-    {
-      "description": "Exactly one scheduling source: akm.schedule or on.",
-      "oneOf": [
-        {
-          "required": ["akm"],
-          "properties": { "akm": { "required": ["schedule"] } },
-          "not": { "required": ["on"] }
-        },
-        {
-          "required": ["on"],
-          "not": {
-            "required": ["akm"],
-            "properties": { "akm": { "required": ["schedule"] } }
-          }
-        }
-      ]
-    }
-  ],
   "definitions": {
     "nonemptyLiteral": {
       "type": "string",
@@ -214,10 +173,106 @@
       "maxLength": 262144,
       "pattern": "^(?:[^\\s:.#/]+//)?(?:commands|workflows|scripts)/(?!\\.{1,2}(?:/|$))[^\\s#\\\\/\\u0000]+(?:/(?!\\.{1,2}(?:/|$))[^\\s#\\\\/\\u0000]+)*$"
     },
-    "githubActionRef": {
+    "akmCommandRef": {
+      "description": "The commands/-only subset of akmExecutableRef — the executable-ref kind whose runtime actually consumes output: (the other consumer, uses: akm/command, is a const, not a ref). Same grammar, with the kind alternation narrowed to commands.",
       "type": "string",
       "maxLength": 262144,
-      "pattern": "^(?!(?:commands|workflows|scripts)/)[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?/(?!\\.{1,2}(?:/|@))[A-Za-z0-9_.-]+(?:/(?!\\.{1,2}(?:/|@))[A-Za-z0-9_.-]+)*@(?![./])(?!.*(?:@|\\.\\.|//|/\\.|\\.(?:/|$)|\\.lock(?:/|$)))[^\\s\\u0000-\\u0020\\u007f~^:?*\\[\\\\/](?:[^\\s\\u0000-\\u0020\\u007f~^:?*\\[\\\\@]*[^\\s\\u0000-\\u0020\\u007f~^:?*\\[\\\\/.@])?$"
+      "pattern": "^(?:[^\\s:.#/]+//)?commands/(?!\\.{1,2}(?:/|$))[^\\s#\\\\/\\u0000]+(?:/(?!\\.{1,2}(?:/|$))[^\\s#\\\\/\\u0000]+)*$"
+    },
+    "taskSourceV4ScheduleEntry": {
+      "description": "One schedule: list entry (D2-N5: per-entry enabled defaults true; inputs are validated against inputs: at parse time and delivered to the scheduled run's own invocation, P2b).",
+      "type": "object",
+      "required": ["cron"],
+      "additionalProperties": false,
+      "properties": {
+        "cron": { "$ref": "#/definitions/nonemptyLiteral" },
+        "enabled": { "type": "boolean" },
+        "inputs": { "$ref": "#/definitions/taskSourceV4ScheduleInputs" }
+      }
+    },
+    "taskSourceV4ScheduleInputs": {
+      "description": "schedule[i].inputs literals: keys are closed to the input-name pattern (the same pattern inputs: declarations use), not the free-form jsonObject shape — the runtime parser additionally rejects any key not present in the document's own inputs: declarations, which static JSON Schema cannot cross-reference here.",
+      "type": "object",
+      "maxProperties": 128,
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/definitions/jsonValue" }
+    },
+    "taskInputName": {
+      "description": "One `inputs:` declaration key. Matches the identifier pattern AND excludes every name `akm task run` reserves for its own flags (src/tasks/task-run-reserved-flags.ts's TASK_RUN_RESERVED_FLAG_NAMES — the union of TASK_RUN_VALUE_FLAGS, TASK_RUN_BOOLEAN_FLAGS, and TASK_RUN_SELF_DIAGNOSED_FLAGS) — declaring an input under one of these names is rejected at parse time (TASK_SOURCE_INVALID, parseInputDeclarations) because the CLI would always treat the flag as its own, never as this input's. `no-quiet`/`no-verbose` are citty's negations of the `quiet`/`verbose` booleans and are listed for completeness even though the identifier pattern already excludes any hyphenated name.",
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+      "not": {
+        "enum": [
+          "bundle",
+          "format",
+          "detail",
+          "shape",
+          "output",
+          "scheduled",
+          "quiet",
+          "verbose",
+          "help",
+          "no-quiet",
+          "no-verbose",
+          "target"
+        ]
+      }
+    },
+    "inputDeclaration": {
+      "description": "One inputs: declaration: a bounded JSON Schema. At the declaration ROOT, required is task source v4's own boolean flag, not JSON Schema's required array; default must itself satisfy the remaining schema; default + required:true together is invalid (D2-N3). Nested schemas (properties/items/allOf/anyOf/oneOf/not) keep ordinary JSON-Schema meaning via outputSchemaDefinition. Closed to exactly this key set — an unlisted keyword (e.g. pattern) is rejected here even though the runtime subset accepts it inside output:, because a task input declaration is intentionally narrower.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "oneOf": [
+            { "$ref": "#/definitions/outputSchemaTypeName" },
+            {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 1024,
+              "items": { "$ref": "#/definitions/outputSchemaTypeName" }
+            }
+          ]
+        },
+        "enum": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1024,
+          "items": {
+            "oneOf": [
+              { "type": "string", "maxLength": 262144 },
+              { "type": "number" },
+              { "type": "boolean" },
+              { "type": "null" }
+            ]
+          }
+        },
+        "properties": {
+          "type": "object",
+          "maxProperties": 256,
+          "propertyNames": { "maxLength": 262144 },
+          "additionalProperties": { "$ref": "#/definitions/outputSchemaDefinition" }
+        },
+        "required": {
+          "description": "Declaration-ROOT required is task source v4's own boolean flag, not a JSON-Schema required array (D2-N3).",
+          "type": "boolean"
+        },
+        "items": { "$ref": "#/definitions/outputSchemaDefinition" },
+        "additionalProperties": { "type": "boolean" },
+        "minItems": { "type": "integer", "minimum": 0 },
+        "maxItems": { "type": "integer", "minimum": 0 },
+        "minLength": { "type": "integer", "minimum": 0 },
+        "maxLength": { "type": "integer", "minimum": 0 },
+        "minimum": { "type": "number" },
+        "maximum": { "type": "number" },
+        "allOf": { "$ref": "#/definitions/outputSchemaArray" },
+        "anyOf": { "$ref": "#/definitions/outputSchemaArray" },
+        "oneOf": { "$ref": "#/definitions/outputSchemaArray" },
+        "not": { "$ref": "#/definitions/outputSchemaDefinition" },
+        "title": { "type": "string", "maxLength": 262144 },
+        "description": { "type": "string", "maxLength": 262144 },
+        "default": { "$ref": "#/definitions/jsonValue" }
+      }
     },
     "outputSchemaDefinition": {
       "type": "object",

package/schemas/akm-workflow.json

@@ -21,6 +21,7 @@
     "stale_after": { "$ref": "akm-asset-envelope.json#/definitions/stale_after" },
     "params": {
       "type": "object",
+      "minProperties": 1,
       "maxProperties": 128,
       "description": "Run parameters: param name -> JSON Schema declaration. Names must be params.<name>-addressable identifiers.",
       "propertyNames": {
@@ -30,6 +31,18 @@
         "$ref": "#/definitions/jsonSchemaObject"
       }
     },
+    "outputs": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 64,
+      "description": "Named, optionally schema-validated projections of step artifacts, exported when the run completes. Names must be steps.<child>.output.<name>-addressable identifiers. Each entry: { from: steps.<id>.output(.<seg>)*, schema?: <bounded JSON Schema> }. Markdown-frontmatter only.",
+      "propertyNames": {
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/outputDeclaration"
+      }
+    },
     "defaults": {
       "$ref": "#/definitions/defaults"
     },
@@ -151,6 +164,21 @@
       "type": "object",
       "description": "A JSON Schema declaration. The parser validates it as a schema definition against the runtime's enforced subset (src/core/json-schema.ts checkJsonSchemaDefinition): typo'd type names and keywords outside the subset (e.g. $ref, const, format, patternProperties) are authoring-time errors, not silent no-ops."
     },
+    "outputDeclaration": {
+      "type": "object",
+      "description": "One outputs: entry: a validated steps.<id>.output(.<seg>)* reference into a step artifact, plus an optional bounded JSON Schema.",
+      "required": ["from"],
+      "additionalProperties": false,
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "A steps.<id>.output(.<seg>)* reference into a step artifact. Never params.<name> — an output projects a step artifact, never a param."
+        },
+        "schema": {
+          "$ref": "#/definitions/jsonSchemaObject"
+        }
+      }
+    },
     "retry": {
       "type": "object",
       "description": "Bounded retry on transient failures, keyed on the persisted failure_reason taxonomy.",