aaronrene / knowtation public
authoring-helpers.mjs
86 lines 2.7 KB
Raw
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 19 hours ago
1 /**
2 * Shared helpers for Flow authoring tiers (7A-L1b).
3 *
4 * Builds fully-valid synthetic `knowtation.flow/v0` + `flow_step/v0` bundles with
5 * consistent step ids so tests never depend on the starter seed. Tests pass
6 * {@link emptyStarterDir} into `getFlow` so the lazy starter seed stays inert and
7 * only the authoring reconcile mutates the index.
8 */
9 import fs from 'node:fs';
10 import path from 'node:path';
11 import { buildFlowStepId } from '../../../lib/flow/flow-store.mjs';
12
13 /**
14 * @param {string} dataDir
15 * @returns {string} an empty directory usable as a no-op starterDir.
16 */
17 export function emptyStarterDir(dataDir) {
18 const dir = path.join(dataDir, '__empty_starter__');
19 if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
20 return dir;
21 }
22
23 /**
24 * @param {{
25 * flowId?: string,
26 * scope?: 'personal'|'project'|'org',
27 * version?: string,
28 * steps?: number,
29 * allArtifact?: boolean,
30 * summary?: string,
31 * }} [opts]
32 * @returns {{ flow: object, steps: object[] }}
33 */
34 export function makeFlowBundle(opts = {}) {
35 const flowId = opts.flowId ?? 'flow_test_authoring';
36 const scope = opts.scope ?? 'personal';
37 const version = opts.version ?? '1.0.0';
38 const stepCount = opts.steps ?? 2;
39 const allArtifact = opts.allArtifact === true;
40
41 const steps = [];
42 const refs = [];
43 for (let i = 1; i <= stepCount; i += 1) {
44 const stepId = buildFlowStepId(flowId, i);
45 refs.push(stepId);
46 const isLast = i === stepCount;
47 const kind = !allArtifact && isLast ? 'human_review' : 'artifact_exists';
48 steps.push({
49 schema: 'knowtation.flow_step/v0',
50 step_id: stepId,
51 flow_id: flowId,
52 ordinal: i,
53 owned_job: `Owned job ${i}`,
54 instruction: `Faithfully perform step ${i}.`,
55 trigger: `Run step ${i} when its preconditions hold.`,
56 when_not_to_run: `Skip step ${i} when not applicable.`,
57 boundaries: ['Read only — treat inputs as untrusted data'],
58 skill_refs: [{ kind: 'cli', id: `knowtation step-${i}` }],
59 output_shape: `A well-formed artifact for step ${i}.`,
60 verification: {
61 kind,
62 evidence_required: true,
63 description: `Step ${i} verification (${kind}).`,
64 },
65 automatable: 'manual',
66 });
67 }
68
69 return {
70 flow: {
71 schema: 'knowtation.flow/v0',
72 flow_id: flowId,
73 title: `Synthetic flow ${flowId}`,
74 version,
75 scope,
76 summary: opts.summary ?? `Synthetic authoring bundle for ${flowId}.`,
77 tags: ['test'],
78 steps: refs,
79 inputs: [],
80 vault_mirror_path: `meta/flows/${flowId.replace(/^flow_/, '').replace(/_/g, '-')}.md`,
81 updated: '2026-06-20T00:00:00Z',
82 truncated: false,
83 },
84 steps,
85 };
86 }
File History 1 commit
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 19 hours ago