@markii/host 0.17.0-next.5 → 0.17.0

package/dist/conformance/host/18-last-run-and-grants/expected.json

@@ -0,0 +1,42 @@
+{
+  "outcomes": [
+    { "kind": "lastRun", "values": {} },
+    {
+      "kind": "ran",
+      "values": { "total": 3 },
+      "failureKinds": [],
+      "traceOk": true
+    },
+    {
+      "kind": "lastRun",
+      "values": { "total": 3 },
+      "valueStatuses": { "total": "stale" },
+      "traceOk": true
+    },
+    {
+      "kind": "ran",
+      "values": { "total": 3 },
+      "failureKinds": [],
+      "traceOk": true
+    },
+    { "kind": "forgotten" },
+    {
+      "kind": "ran",
+      "values": { "total": 3 },
+      "failureKinds": [],
+      "traceOk": true
+    }
+  ],
+  "diagnostics": [
+    "manual run: net declaration mismatch",
+    "uses net access to api.example.com",
+    "manual run: net declaration mismatch",
+    "uses net access to api.example.com",
+    "manual run: net declaration mismatch",
+    "uses net access to api.example.com"
+  ],
+  "prompts": [
+    "This note's scripts can send data to api.example.com. Allow?",
+    "This note's scripts can send data to api.example.com. Allow?"
+  ]
+}

package/dist/conformance/host/18-last-run-and-grants/note.mk.md

@@ -0,0 +1,5 @@
+# Last run and grants
+
+```lua {name=total}
+return net.fetch_json("https://api.example.com/orders")
+```

package/dist/conformance/host/18-last-run-and-grants/scenario.json

@@ -0,0 +1,27 @@
+{
+  "id": "last-run-and-grants",
+  "invariant": "a run's values and trace can be read back with no storage key, and clearing the stored grants makes the next manual run prompt again",
+  "clock": 1700000000000,
+  "actions": [
+    { "type": "lastRun" },
+    {
+      "type": "run",
+      "trigger": "manual",
+      "answers": ["allow"],
+      "simulate": { "name": "total", "value": 3, "requiresHost": "api.example.com" }
+    },
+    { "type": "lastRun" },
+    {
+      "type": "run",
+      "trigger": "manual",
+      "simulate": { "name": "total", "value": 3, "requiresHost": "api.example.com" }
+    },
+    { "type": "forgetGrants" },
+    {
+      "type": "run",
+      "trigger": "manual",
+      "answers": ["allow"],
+      "simulate": { "name": "total", "value": 3, "requiresHost": "api.example.com" }
+    }
+  ]
+}

package/dist/conformance/host/README.md

@@ -47,6 +47,8 @@ needs, is the runner's own `ACTION_CAPABILITY` map:
 |---|---|
 | `open` | (always supported) |
 | `run` | `isolate` |
+| `lastRun` | (always supported) |
+| `forgetGrants` | (always supported) |
 | `exportHtml` | `export-format` (`html`) |
 | `exportAnsi` | `export-format` (`ansi`) |
 | `exportLinkedSet` | `linked-set-export` (a `resolveLinkedSetTarget`) |
@@ -137,6 +139,9 @@ coarse, matching each `kind`:
   (`{name: value}`); `failureKinds` compares the closed `FailureKind`
   taxonomy only, never a raw message or a timing; an optional `traceOk`
   compares the recorded run trace's `ok` flag.
+- `lastRun`: `values` compares the stored values shown on open, by name,
+  like `ran`. `valueStatuses` compares each value's status by name, and
+  `traceOk` compares the recorded trace's `ok` flag.
 - `exported`: `contains`/`excludes` are substrings checked against the
   written file's content, never the whole document, the render corpora
   already pin bytes. `valueCount` is how many last-run values were baked
@@ -147,7 +152,8 @@ coarse, matching each `kind`:
   of the folder the pack was unzipped into.
 - `declined`: `step` (`'consent'`/`'replace'`, or absent for the
   scripts-disabled synthetic outcome) and `reasonContains`, a substring of
-  the user-facing reason.
+  the user-facing reason. A user's "no" to a prompt and a cancelled picker
+  are both `declined`.
 - `listed`: `enabled` and `notEnabled`, namespace lists, order-independent.
 - `enabled`, `disabled`, `placed`, `removed`: `namespace`.
 - `loaded`: `namespaces`, order-independent.
@@ -159,8 +165,8 @@ coarse, matching each `kind`:
   accepted container item.
 - `hover`: `contains`, a substring of the hover text. Optional `start` and
   `end` compare the hovered name's columns.
-- every other `kind` (`opened`, `none`, `not-found`, `failed`, `rejected`,
-  `reserved`, `cancelled`, `inserted`): `kind` equality is the whole check.
+- every other `kind` (`opened`, `none`, `not-found`, `failed`, `invalid`,
+  `reserved`, `forgotten`, `inserted`): `kind` equality is the whole check.
 
 An action whose capability the adapter under test does not declare is
 never diffed against `expected.json` at all (see "Capability handling"
@@ -200,7 +206,7 @@ run the whole corpus honestly: its result records say `unsupported`
 where it genuinely offers nothing, which is the truth and is visible,
 rather than a skipped test or a faked empty answer.
 
-## The sixteen scenarios
+## The scenarios
 
 | id | what it proves |
 |---|---|
@@ -221,6 +227,7 @@ rather than a skipped test or a faked empty answer.
 | `15-load-packs-engine-views` | loading packs reports every installed component and, as `unavailable`, the ones this host's engine has no view for |
 | `16-pack-trust` | a folder that arrives without consent is listed as present and never loaded; enable, disable, re-enable and remove move the device trust list; a host without the list reports the whole scenario `unsupported` |
 | `17-export-linked-set` | a note and the notes it links to export as one archive with an index page; a host with no linked-set target reports `unsupported` |
+| `18-last-run-and-grants` | a run's values and trace read back through `lastRun` with no storage key, and clearing the grants makes the next manual run prompt again |
 
 The capabilities an adapter declares decide which scenarios report
 `unsupported` on that host. That is a reported gap and not a corpus defect.

package/dist/conformance.d.ts

@@ -1,2 +1,2 @@
-export { ACTION_CAPABILITY, assertHostScenario, containsInOrder, createAnswerQueue, hostConformanceDir, hostDeclaresCapability, listHostScenarioNames, loadHostScenario, outcomeMismatches, runHostScenario, zipArchiveDirectory, } from './host/conformance-runner.js';
+export { assertHostScenario, createAnswerQueue, hostConformanceDir, listHostScenarioNames, loadHostScenario, runHostScenario, } from './host/conformance-runner.js';
 export type { HostScenario, HostScenarioAction, HostScenarioCapability, HostScenarioExpected, HostScenarioRunResult, LoadedHostScenario, RunSimulation, } from './host/conformance-runner.js';

package/dist/conformance.js

@@ -2,4 +2,4 @@
 // the corpus from disk and drives a real adapter). A host's adapter test
 // imports this to run `conformance/host/` against its own `HostAdapter`.
 // The corpus ships inside the package at `dist/conformance/host/`.
-export { ACTION_CAPABILITY, assertHostScenario, containsInOrder, createAnswerQueue, hostConformanceDir, hostDeclaresCapability, listHostScenarioNames, loadHostScenario, outcomeMismatches, runHostScenario, zipArchiveDirectory, } from './host/conformance-runner.js';
+export { assertHostScenario, createAnswerQueue, hostConformanceDir, listHostScenarioNames, loadHostScenario, runHostScenario, } from './host/conformance-runner.js';

package/dist/host/adapter.d.ts

@@ -54,9 +54,9 @@ export type HostIsolate = {
      */
     workerPath(): string;
     /**
-     * Creates the worker-thread isolate: `workerThreadIsolate` from
-     * `@markii/host/node`. Injected so the shared run path imports
-     * nothing from `node:*`.
+     * Creates the worker-thread isolate. `createNodeHostIsolate()` from
+     * `@markii/host/node` supplies it. Injected so the shared run path
+     * imports nothing from `node:*`.
      */
     readonly spawnIsolate: IsolateSpawner;
 } | {
@@ -155,16 +155,30 @@ export interface HostPackSource {
 }
 /** Every export format any host offers today. */
 export type HostExportFormat = 'html' | 'pdf' | 'ansi' | 'md-plain';
+/**
+ * What a host declares to offer exports. A request can carry its own
+ * `targetPath`, so a host with no picker (the command line tool, or a call
+ * site that already knows where the file goes) leaves the resolvers out.
+ *
+ * A single-note export needs `exports` declared with the format in
+ * `formats`, and a destination: either a `resolveTarget` or the request's
+ * `targetPath`. Without a destination it answers `unsupported`.
+ *
+ * The linked-set export is offered when `exports` is declared and the host
+ * has a `resolveLinkedSetTarget` or the request carries a `targetPath`.
+ * Without either it answers `unsupported`. A host that declares `exports`
+ * with neither resolver, such as the command line tool, therefore offers
+ * the linked-set export only to a caller that names the path.
+ */
 export interface HostExportCapabilities {
     readonly formats: ReadonlySet<HostExportFormat>;
-    /** GUI hosts show a picker; the CLI returns the path it was given. */
-    resolveTarget(suggestedFileName: string, format: HostExportFormat): Promise<string | undefined>;
+    /** GUI hosts show a picker; the CLI returns the path it was given. Resolves `undefined` when the user cancels. Absent for a host whose callers always pass `targetPath`. */
+    resolveTarget?(suggestedFileName: string, format: HostExportFormat): Promise<string | undefined>;
     /** Only present on a host declaring `'pdf'`. The one Electron-touching seam. */
     htmlToPdf?(html: string): Promise<Uint8Array>;
     /**
      * Names the zip archive of a linked-set export, or resolves `undefined`
-     * when the user cancels. Present only on a host that offers the
-     * linked-set export; a host can offer single-note export without it
+     * when the user cancels. A host can offer single-note export without it
      * (the command line tool does), so it is a member of its own rather than
      * a `HostExportFormat`.
      */

package/dist/host/cascade-export-behavior.d.ts

@@ -124,6 +124,8 @@ export declare function cascadeDiagnosticLines(outcome: CascadeExportOutcome): s
 export interface LinkedSetExportInputs extends Omit<CascadeArchiveRequest, 'readNote'> {
     /** The suggested archive file name handed to the host's picker. */
     readonly suggestedFileName: string;
+    /** Where to write the archive. When present the adapter's `resolveLinkedSetTarget` is not asked. */
+    readonly targetPath?: string;
 }
 /**
  * Exports a note and the notes it links to as one archive: resolves the
@@ -131,6 +133,6 @@ export interface LinkedSetExportInputs extends Omit<CascadeArchiveRequest, 'read
  * note through `adapter.readFile`, writes it through `adapter.writeFile`,
  * and sends the diagnostics lines to `adapter.diagnostics`. Resolves
  * `undefined` when the host has no linked-set target or its picker was
- * cancelled. Never throws.
+ * cancelled. A `targetPath` skips the picker. Never throws.
  */
 export declare function exportLinkedSetViaAdapter(adapter: HostAdapter, inputs: LinkedSetExportInputs): Promise<CascadeExportOutcome | undefined>;

package/dist/host/cascade-export-behavior.js

@@ -155,17 +155,20 @@ export function cascadeDiagnosticLines(outcome) {
  * note through `adapter.readFile`, writes it through `adapter.writeFile`,
  * and sends the diagnostics lines to `adapter.diagnostics`. Resolves
  * `undefined` when the host has no linked-set target or its picker was
- * cancelled. Never throws.
+ * cancelled. A `targetPath` skips the picker. Never throws.
  */
 export async function exportLinkedSetViaAdapter(adapter, inputs) {
     const resolveTarget = adapter.exports?.resolveLinkedSetTarget;
-    if (resolveTarget === undefined)
+    const { suggestedFileName, targetPath, ...archiveRequest } = inputs;
+    if (targetPath === undefined && resolveTarget === undefined) {
         return undefined;
-    const { suggestedFileName, ...archiveRequest } = inputs;
+    }
     let path;
     let outcome;
     try {
-        path = await resolveTarget.call(adapter.exports, suggestedFileName);
+        path =
+            targetPath ??
+                (await resolveTarget?.call(adapter.exports, suggestedFileName));
         if (path === undefined)
             return undefined;
         const target = path;

package/dist/host/conformance-runner.d.ts

@@ -31,6 +31,14 @@ export type HostScenarioAction = {
     /** When `true`, this action never reaches `host.run` at all — see this file's top comment on the scripts-disabled scenario. */
     readonly scriptsDisabled?: boolean;
     readonly simulate?: RunSimulation;
+}
+/** Reads what the note's last run left: the values to show on open and the trace. */
+ | {
+    readonly type: 'lastRun';
+}
+/** Clears the note's stored script grants. */
+ | {
+    readonly type: 'forgetGrants';
 } | {
     readonly type: 'exportHtml';
 } | {

package/dist/host/conformance-runner.js

@@ -44,7 +44,7 @@ import { usesPackTrust } from './pack-trust-behavior.js';
 import { join, relative, sep } from 'node:path';
 import { unzipSync, zipSync } from 'fflate';
 import { conformanceDir } from '@markii/core/corpus';
-import { createMarkiiHost, } from './create-host.js';
+import { createMarkiiHostWithSeams, } from './create-host.js';
 import { scriptsDisabledDiagnosticLine, scriptsDisabledNotice, } from './script-execution.js';
 // --- corpus location ----------------------------------------------------
 /**
@@ -99,6 +99,8 @@ export function zipArchiveDirectory(archiveDir) {
 export const ACTION_CAPABILITY = {
     open: undefined,
     run: 'isolate',
+    lastRun: undefined,
+    forgetGrants: undefined,
     exportHtml: 'export-format',
     exportAnsi: 'export-format',
     exportLinkedSet: 'linked-set-export',
@@ -258,7 +260,7 @@ export async function runHostScenario(adapter, scenario, noteText, scenarioDir,
         },
     };
     let currentSimulation;
-    const host = createMarkiiHost(recording, {
+    const host = createMarkiiHostWithSeams(recording, {
         // The runner is Node-only test tooling, so it supplies the real Node
         // implementations of the seams the host layer takes by injection.
         htmlEngine: createHtmlExportEngine(),
@@ -324,6 +326,18 @@ async function runOneAction(host, adapter, action, ctx) {
                 trigger: action.trigger,
             });
         }
+        case 'lastRun': {
+            const last = host.lastRun(ctx.notePath);
+            return {
+                kind: 'lastRun',
+                values: last.values,
+                persistedValues: last.persistedValues,
+                ...(last.trace !== undefined ? { trace: last.trace } : {}),
+            };
+        }
+        case 'forgetGrants':
+            await host.forgetGrants(ctx.notePath);
+            return { kind: 'forgotten' };
         case 'exportHtml':
         case 'exportAnsi': {
             const outcome = await host.exportNote({
@@ -475,6 +489,30 @@ export function outcomeMismatches(actual, expected) {
             }
             break;
         }
+        case 'lastRun': {
+            const wantValues = expected['values'] ?? {};
+            const gotValues = landedValues(actualRecord['values']);
+            if (JSON.stringify(gotValues) !== JSON.stringify(wantValues)) {
+                mismatches.push(`values: expected ${JSON.stringify(wantValues)}, got ${JSON.stringify(gotValues)}`);
+            }
+            if (expected['valueStatuses'] !== undefined) {
+                const statuses = {};
+                const raw = (actualRecord['values'] ?? {});
+                for (const [name, entry] of Object.entries(raw)) {
+                    statuses[name] = entry.status;
+                }
+                if (JSON.stringify(statuses) !== JSON.stringify(expected['valueStatuses'])) {
+                    mismatches.push(`value statuses: expected ${JSON.stringify(expected['valueStatuses'])}, got ${JSON.stringify(statuses)}`);
+                }
+            }
+            if (expected['traceOk'] !== undefined) {
+                const trace = actualRecord['trace'];
+                if (trace?.ok !== expected['traceOk']) {
+                    mismatches.push(`trace.ok: expected ${String(expected['traceOk'])}, got ${String(trace?.ok)}`);
+                }
+            }
+            break;
+        }
         case 'exported': {
             if (expected['valueCount'] !== undefined &&
                 actualRecord['valueCount'] !== expected['valueCount']) {