apexrest 1.2.0 → 1.3.0

package/dist/resources/schemas/policy.schema.json

@@ -42,6 +42,27 @@
           "planDigest": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$"
+          },
+          "note": {
+            "type": "string",
+            "maxLength": 2000
+          },
+          "grantedBy": {
+            "type": "string",
+            "enum": [
+              "user",
+              "ship"
+            ]
+          },
+          "grantedAt": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
+          },
+          "workerPid": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
           }
         },
         "required": [

package/dist/resources/schemas/project.schema.json

@@ -140,13 +140,6 @@
           "expectedMarker": {
             "type": "string",
             "minLength": 1
-          },
-          "deploymentControl": {
-            "type": "string",
-            "enum": [
-              "local",
-              "database"
-            ]
           }
         },
         "required": [
@@ -215,6 +208,23 @@
       ],
       "additionalProperties": false
     },
+    "deploymentControl": {
+      "type": "string",
+      "const": "local"
+    },
+    "composer": {
+      "type": "object",
+      "properties": {
+        "allowSourceOnly": {
+          "default": false,
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "allowSourceOnly"
+      ],
+      "additionalProperties": false
+    },
     "artifacts": {
       "type": "object",
       "properties": {

package/dist/resources/schemas/sync-state.schema.json

@@ -0,0 +1,238 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "syncId": {
+      "type": "string",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "projectRoot": {
+      "type": "string"
+    },
+    "projectId": {
+      "type": "string"
+    },
+    "environment": {
+      "type": "string"
+    },
+    "targetDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "target": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    },
+    "sourceDir": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "toolchainDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "runtimeVersion": {
+      "type": "string"
+    },
+    "compilerVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "exportedAt": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
+    },
+    "baseline": {
+      "type": "object",
+      "properties": {
+        "directory": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "files": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      },
+      "required": [
+        "directory",
+        "files",
+        "digest"
+      ],
+      "additionalProperties": false
+    },
+    "backup": {
+      "type": "object",
+      "properties": {
+        "backupId": {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+        },
+        "checksum": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      },
+      "required": [
+        "backupId",
+        "checksum"
+      ],
+      "additionalProperties": false
+    },
+    "observedMetadata": {
+      "type": "object",
+      "properties": {
+        "lastUpdatedOn": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "lastUpdatedBy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "lastUpdatedOn",
+        "lastUpdatedBy"
+      ],
+      "additionalProperties": false
+    },
+    "lastSuccessfulImport": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "at": {
+              "type": "string",
+              "format": "date-time",
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
+            },
+            "runId": {
+              "type": "string",
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+            },
+            "snapshot": {
+              "type": "object",
+              "properties": {
+                "directory": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 1024
+                },
+                "files": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1024
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$"
+                  }
+                },
+                "digest": {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                }
+              },
+              "required": [
+                "directory",
+                "files",
+                "digest"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "required": [
+            "at",
+            "runId",
+            "snapshot"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "ready",
+        "importing",
+        "verification_failed",
+        "outcome_unknown",
+        "invalidated"
+      ]
+    },
+    "importingRunId": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "uuid",
+          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "syncId",
+    "revision",
+    "projectRoot",
+    "projectId",
+    "environment",
+    "targetDigest",
+    "target",
+    "sourceDir",
+    "toolchainDigest",
+    "runtimeVersion",
+    "compilerVersion",
+    "exportedAt",
+    "baseline",
+    "backup",
+    "observedMetadata",
+    "lastSuccessfulImport",
+    "status",
+    "importingRunId"
+  ],
+  "additionalProperties": false
+}

package/dist/resources/templates/blank-app/README.md

@@ -1,5 +1,3 @@
 # Blank application
 
-English | [Українська](README.uk.md)
-
 This is a real Oracle SQLcl-generated starter reference with its original `.apex/apexlang.json`. New projects run the real generator; they do not fabricate metadata from this fixture. Requires SQLcl 26.1.2+ and Java 21. Authentication remains the Oracle starter default. Local compilation has been verified; deployment requires an explicitly configured APEX 26.1+ workspace/schema.

package/dist/resources/templates/customer-crm/README.md

@@ -1,7 +1,5 @@
 # Customer CRM
 
-English | [Українська](README.uk.md)
-
 A real APEXlang overlay on the Oracle-generated starter: customers report (page 10), dashboard (20), modal form (80), server validation package/trigger, immutable table migration, utPLSQL tests and authenticated browser CRUD with unique synthetic records. It retains default authentication; configure a dedicated test account through authorized APEX administration. No password or ORDS endpoint is included.
 
-`project init ./crm --template customer-crm` generates fresh Oracle metadata and applies the reviewed overlay. Local SQLcl compilation passed on 26.1.2 with MMD 26.1.0+3102. Live target deployment, test selectors and SQL results still need integration evidence. Required suites are SQL and E2E. Configure the environment and authorized test grants, provide utPLSQL for the SQL suite, then authenticate interactively. Control tables are needed only for explicitly selected database coordination; local coordination is the default.
+`project init ./crm --template customer-crm` generates fresh Oracle metadata and applies the reviewed overlay. Local SQLcl compilation passed on 26.1.2 with MMD 26.1.0+3102. Live target deployment, test selectors and SQL results still need integration evidence. Required suites are SQL and E2E. Configure the environment and authorized test grants, provide utPLSQL for the SQL suite, then authenticate interactively.

package/dist/resources/templates/existing-app/README.md

@@ -1,7 +1,5 @@
 # Adopt an existing application
 
-English | [Українська](README.uk.md)
-
 Create an `existing-app` project skeleton, configure the exact existing test target and named read connection, then run `project adopt --env dev --app-id ID`. It exports through a private staging directory and installs only into a new source directory. If that directory exists, adoption fails with LOCAL_EDITS_CONFLICT; local edits are preserved. For later exports use a fresh `apex export --env dev --output review/export-UUID` directory.
 
 Keep `.apex`, Oracle IDs, shared LOVs, authentication and all page files under version control. `apex diff --env dev` compares source file hashes with a fresh Oracle export. It is a textual inventory, not proof of complete semantic component coverage. SQLcl exports use original IDs and omit export timestamps; no invented normalization removes metadata.

package/dist/resources/third-party/node_modules__yaml__LICENSE

@@ -0,0 +1,13 @@
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/dist/runtime/apexrest.mjs

@@ -2,20 +2,21 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   dispatch,
+  executeJob,
+  failQueuedJob,
+  internalOperations,
   schemas
-} from "./chunk-TXVQLYTH.mjs";
-import {
-  executeJob
-} from "./chunk-BD2AVCFU.mjs";
-import "./chunk-4MYHJ2IU.mjs";
-import "./chunk-S24BD6PY.mjs";
+} from "./chunk-5PCC7GZM.mjs";
+import "./chunk-TMSMKVRP.mjs";
+import "./chunk-RBJJNQ5O.mjs";
 import {
   loadProject
-} from "./chunk-3MDDJFXN.mjs";
+} from "./chunk-N4C2SKCN.mjs";
+import "./chunk-JYN3YHP3.mjs";
 import {
   Fault,
   failure
-} from "./chunk-2Z3BZF66.mjs";
+} from "./chunk-WPS3CSQJ.mjs";
 
 // packages/cli/src/main.ts
 var argv = process.argv.slice(2);
@@ -30,29 +31,36 @@ var positional = {
   "jobs.cancel": ["id"],
   "artifacts.read": ["id"]
 };
+var groupAliases = { job: "jobs", reference: "docs" };
+var variadic = { "docs.search": "query" };
 function operationFrom(args) {
-  const first = args[0];
-  if (["doctor", "version", "setup"].includes(first ?? "")) return { op: first, start: 1 };
+  const first = groupAliases[args[0] ?? ""] ?? args[0];
+  if (["doctor", "version", "setup", "ship", "status"].includes(first ?? "")) return { op: first, start: 1 };
   if (first === "test" && ["unit", "sql", "api", "e2e", "all"].includes(args[1] ?? ""))
     return { op: "test.run", start: 2, suite: args[1] };
-  return { op: args.slice(0, 2).join("."), start: 2 };
+  return { op: [first, args[1]].join("."), start: 2 };
 }
+var listed = (op) => !internalOperations.includes(op);
 var selected = operationFrom(argv);
+function knownHelpTarget() {
+  const first = argv[0] ?? "";
+  return first.startsWith("-") || ["mcp", "test"].includes(first) || selected.op in schemas || // A command group alone (apexrest deploy --help) lists the general help.
+  (argv[1] ?? "-").startsWith("-") && Object.keys(schemas).some((op) => op.startsWith((groupAliases[first] ?? first) + "."));
+}
 function help() {
   const key = selected.op;
   const lines = [
     "APEXREST for Codex \u2014 independent Oracle APEX developer tools",
     "Usage: apexrest [command] [options]",
-    "Run apexrest in a terminal to manage tools, plugins and saved SQLcl connections.",
-    "  tui [--project PATH]   Open the terminal UI explicitly",
-    "  panel tui [--project PATH]   Live development panel inside Codex CLI",
     "",
-    ...Object.keys(schemas).filter((x) => x !== "test.run").map((x) => "  " + x.replace(".", " ")),
+    ...Object.keys(schemas).filter((x) => x !== "test.run" && listed(x)).map((x) => "  " + x.replace(".", " ")),
     "  test unit|sql|api|e2e|all [--env NAME]",
+    "  job status|cancel <id>   (alias of jobs ...)",
     "  mcp",
     "",
     "--json emits one structured JSON result; diagnostics use stderr.",
     "Use --project PATH for project operations. Environment never defaults.",
+    "ship --env NAME --mode plan|apply --user-request TEXT validates, plans and (apply) imports with a plan-bound grant.",
     "Exit codes: 0 success, 1 failed, 2 input, 3 dependency, 4 approval, 5 conflict, 6 unknown/cancelled."
   ];
   if (schemas[key])
@@ -64,10 +72,19 @@ function help() {
       ),
       ...(positional[key] ?? []).map((p) => "  <" + p + ">")
     );
+  if (key === "apex.sync")
+    lines.push(
+      "",
+      "--env NAME --action init|status|refresh|invalidate",
+      "status is local only. init reuses a valid baseline; refresh refuses dirty sources.",
+      "The initial SQL backup restores the baseline only. Interrupted imports require reconciliation."
+    );
+  if (key === "apex.diff")
+    lines.push("", "--comparison auto|live: auto uses an active local checkpoint; live explicitly exports.");
   if (key === "docs.search")
     lines.push(
       "",
-      "--corpus apexlang|components|patterns selects the offline catalog (default: apexlang).",
+      "--corpus apexlang|components|patterns|blocks|blueprints selects the offline catalog (default: apexlang).",
       "Filter with --kind, --family and --version; follow nextResultOffset using --offset for more hits."
     );
   if (key === "docs.read")
@@ -76,16 +93,31 @@ function help() {
       "Read a result ID, grammar:production-name, component: ID or pattern: ID.",
       "Follow nextOffset using --offset; catalog navigationOffset recovers all dependency links."
     );
-  if (key === "panel.action")
+  if (key === "panel.status")
     lines.push(
       "",
-      "Pass --action as one JSON object. Supported kinds: preferences, sqlcl, connection, cancel-job, validate, test, browser, plan.",
-      `Example: apexrest panel action --action '{"kind":"validate"}' --project PATH --json`
+      "Read-only local snapshot: settings, connections, Git changes, sync state, jobs and deployment journal.",
+      "No server, worker, job or database call is started. Same as: apexrest status --detail project --project PATH --json"
     );
   if (key === "jobs.status")
     lines.push(
-      "Use --wait-seconds 25 to wait for an existing job without repeated status calls (default: immediate)."
+      "Use --wait-seconds N (up to 120) to wait for an existing job without repeated status calls (default: immediate)."
+    );
+  if (key === "ship")
+    lines.push(
+      "",
+      "mode plan: validate with the Oracle compiler, read the target and write .apexrest/plans/ship-<id>.json for review.",
+      "mode apply: non-production only. Records a deploy grant bound to this project, target and plan digest with the",
+      "user's literal --user-request, imports with backup/drift/identity checks, verifies, runs required suites, then",
+      "removes the grant. Production targets require the protected CI approval path (deploy apply)."
+    );
+  if (key === "status")
+    lines.push(
+      "",
+      "--detail doctor probes local tools; --detail project (default) prints the read-only project snapshot."
     );
+  if (key === "apex.validate")
+    lines.push("", "Runs in-process and returns structured diagnostics (file, line, column, type, hint).");
   if (key === "dependencies.install")
     lines.push(
       "",
@@ -124,7 +156,7 @@ function help() {
       "cli: SQLcl subprocess (default). mcp: official SQLcl stdio server (sql -mcp).",
       "direct: Oracle listener connection (default). ords: SQLcl OREST over HTTP(S), without port 1521.",
       "ORDS uses SQLcl CLI; select --mode cli with --database-transport ords.",
-      "Configure the ORDS URL, username and password for each reference using connection add or panel Settings.",
+      "Configure the ORDS URL, username and password for each reference using connection add.",
       "--mcp-restrict-level 4|1: 4 is the default; 1 explicitly permits scripts but blocks host commands.",
       "Saved in APEXREST_HOME/sqlcl.json. No connection, download or Codex registration is changed.",
       "SQLcl MCP can write its own database audit log on connected operations. No silent CLI fallback."
@@ -132,28 +164,26 @@ function help() {
   console.log(lines.join("\n"));
 }
 try {
-  if (argv.includes("--help") || argv.includes("-h")) help();
-  else if (argv[0] === "tui" || !argv.length && process.stdin.isTTY && process.stdout.isTTY && process.env.TERM !== "dumb") {
-    if (argv.length > 1 && (argv.length !== 3 || argv[1] !== "--project" || !argv[2] || argv[2].startsWith("--")))
-      throw new Fault("INVALID_INPUT", "Usage: apexrest tui [--project PATH]", 2);
-    const { runTui } = await import("./chunk-7RZW5QV2.mjs");
-    await runTui(argv[2] ? { project: argv[2] } : {});
+  if (argv.includes("--help") || argv.includes("-h")) {
+    if (!knownHelpTarget())
+      throw new Fault(
+        "INVALID_INPUT",
+        `Unknown command: ${argv.filter((a) => !a.startsWith("-")).join(" ")}. Use apexrest --help.`,
+        2
+      );
+    help();
   } else if (!argv.length) help();
-  else if (argv[0] === "panel" && argv[1] === "tui") {
-    if (argv.length !== 2 && (argv.length !== 4 || argv[2] !== "--project" || !argv[3]))
-      throw new Fault("INVALID_INPUT", "Usage: apexrest panel tui [--project PATH]", 2);
-    const { runPanelTui } = await import("./chunk-SPZVXAM5.mjs");
-    await runPanelTui(argv[3] ?? process.cwd());
-  } else if (argv[0] === "--panel-worker") {
-    if (argv.length !== 2 || !argv[1]) throw new Fault("INVALID_INPUT", "Invalid panel worker request.", 2);
-    const { servePanel } = await import("./chunk-IX6V6ZGW.mjs");
-    await servePanel(argv[1]);
-  } else if (argv[0] === "--job-worker") {
+  else if (argv[0] === "--job-worker") {
     if (argv.length !== 3) throw new Fault("INVALID_INPUT", "Invalid internal job request.", 2);
-    await executeJob(await loadProject(argv[1]), argv[2], dispatch);
+    try {
+      await executeJob(await loadProject(argv[1]), argv[2], dispatch);
+    } catch (error) {
+      await failQueuedJob(argv[1], argv[2], error).catch(() => void 0);
+      throw error;
+    }
   } else if (argv[0] === "mcp") {
     if (argv.length !== 1) throw new Fault("INVALID_INPUT", "mcp accepts no arguments.", 2);
-    const { startMcp } = await import("./chunk-YLXJ6H4J.mjs");
+    const { startMcp } = await import("./chunk-QKYF6N6U.mjs");
     await startMcp();
   } else {
     const selectedOp = argv[0] === "--version" ? { op: "version", start: 1 } : selected;
@@ -172,10 +202,12 @@ try {
       "nativeOnly",
       "keepRuntime",
       "headed",
-      "saved"
+      "saved",
+      "workingCopy",
+      "includeUnresolved"
     ]);
     const numbers = /* @__PURE__ */ new Set(["appId", "offset", "limit", "waitSeconds"]);
-    let index = 0;
+    let index = 0, rest;
     for (let i = selectedOp.start; i < argv.length; i++) {
       const token = argv[i];
       if (token.startsWith("--")) {
@@ -188,12 +220,16 @@ try {
           const value = argv[++i];
           if (!value || value.startsWith("--"))
             throw new Fault("INVALID_INPUT", `Missing value for ${token}`, 2);
-          input[name] = name === "action" && selectedOp.op === "panel.action" ? JSON.parse(value) : numbers.has(name) ? Number(value) : value;
+          input[name] = numbers.has(name) ? Number(value) : value;
         }
       } else {
-        const field = positional[selectedOp.op]?.[index++];
-        if (!field || field in input) throw new Fault("INVALID_INPUT", `Unexpected argument: ${token}`, 2);
-        input[field] = token;
+        const field = positional[selectedOp.op]?.[index];
+        if (field && !(field in input)) {
+          index++;
+          input[field] = token;
+          if (variadic[selectedOp.op] === field) rest = field;
+        } else if (!field && rest) input[rest] = input[rest] + " " + token;
+        else throw new Fault("INVALID_INPUT", `Unexpected argument: ${token}`, 2);
       }
     }
     const result = await dispatch(selectedOp.op, input);