sitelooper 0.3.0

package/dist/spec/locators.js

@@ -0,0 +1,270 @@
+import { specOf } from '../skills/replay.js';
+import { VOLATILE_TOKEN_SHAPE, WILDCARD, volatileMatcher } from '../shared/text.js';
+const SLOT = /\{\{([vd]\d+)\}\}/;
+const SLOT_G = new RegExp(SLOT.source, 'g');
+const defaultSlot = (s) => '${p.' + s + '}';
+/** The escapes a single-quoted and a template literal share. */
+function escapeFor(text) {
+    return text
+        .replace(/\\/g, '\\\\')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+/** A JS single-quoted string literal for `text`. */
+function quote(text) {
+    return `'${escapeFor(text).replace(/'/g, "\\'")}'`;
+}
+/** Literal text inside a template literal: a backtick or a `${` would end it or open a hole. */
+function escapeTemplate(text) {
+    return escapeFor(text).replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+}
+/** JS string source for recorded text: a single-quoted literal, or a template literal when it
+ *  carries {{slots}}. */
+export function stringSource(text, o = {}) {
+    if (!SLOT.test(text))
+        return quote(text);
+    const slot = o.slot ?? defaultSlot;
+    // split() with one capture group alternates literal, slot name, literal...
+    const body = text
+        .split(SLOT_G)
+        .map((p, i) => (i % 2 ? slot(p) : escapeTemplate(p)))
+        .join('');
+    return `\`${body}\``;
+}
+// The \u0001 delimiters keep a sentinel's digits from fusing with neighbouring
+// text into a clock or date token, and escapeRe leaves all three characters
+// alone, so the sentinel comes back out of the pattern intact.
+const SENTINEL = (i) => `\u0001${i}\u0001`;
+const SENTINEL_G = /\u0001(\d+)\u0001/g;
+/**
+ * The pieces of the RegExp `volatileMatcher` would build, with the slots
+ * pulled back out - or null when it would return a plain string.
+ *
+ * Built by asking volatileMatcher itself rather than restating its token
+ * shape here: each slot is swapped for a sentinel that survives its escaping
+ * untouched, and the sentinels are cut back out of the resulting `source`.
+ * Duplicating the wildcard pattern would let the two drift, and the whole
+ * point of this module is that they cannot.
+ *
+ * Volatility is judged with the slots still unbound, because a parameter is
+ * unknown at compile time: a date arriving through `{{v1}}` stays an exact
+ * match in the spec where replay would have wildcarded it. Stricter, never
+ * looser - a spec that quietly matched another day's row would be a lie.
+ */
+function matcherPieces(text) {
+    const names = [];
+    const probe = text.replace(SLOT_G, (_m, name) => {
+        names.push(name);
+        return SENTINEL(names.length - 1);
+    });
+    const matcher = volatileMatcher(probe);
+    if (typeof matcher === 'string')
+        return null;
+    const pieces = [];
+    let last = 0;
+    for (const m of matcher.source.matchAll(SENTINEL_G)) {
+        const at = m.index ?? 0;
+        if (at > last)
+            pieces.push({ lit: matcher.source.slice(last, at) });
+        pieces.push({ slot: names[Number(m[1])] });
+        last = at + m[0].length;
+    }
+    if (last < matcher.source.length)
+        pieces.push({ lit: matcher.source.slice(last) });
+    return pieces;
+}
+/** The expression inside a slot's interpolation, so it can be wrapped in escapeRe(). */
+function slotExpr(name, o) {
+    const rendered = (o.slot ?? defaultSlot)(name);
+    return /^\$\{[\s\S]*\}$/.test(rendered) ? rendered.slice(2, -1) : null;
+}
+/** Source for the matcher makeLocator would build: stringSource, or a RegExp literal when
+ *  volatileMatcher would return a RegExp (mirror its construction exactly; slots inside a
+ *  regex become `${escapeRe(p.vN)}` via new RegExp(...) source). */
+export function matcherSource(text, o = {}) {
+    const pieces = matcherPieces(text);
+    if (!pieces)
+        return stringSource(text, o);
+    if (!pieces.some((p) => 'slot' in p)) {
+        const source = pieces.map((p) => p.lit).join('');
+        // A literal keeps the generated file readable, and RegExp.source is
+        // already literal-safe - it escapes the slashes that would end one, which
+        // is why nothing is escaped again here. Only a line terminator has no
+        // literal form, so that case goes through new RegExp.
+        return /[\n\r\u2028\u2029]/.test(source) ? `new RegExp(${quote(source)})` : `/${source}/`;
+    }
+    // escapeRe is inlined into the generated file: a bound parameter is DATA, so
+    // its own regex metacharacters must not become pattern - which is exactly
+    // what volatileMatcher does to the recorded text before splicing in the
+    // wildcards.
+    const body = pieces
+        .map((p) => {
+        if ('lit' in p)
+            return escapeTemplate(p.lit);
+        const expr = slotExpr(p.slot, o);
+        // A caller whose slot renderer is not an interpolation owns its own
+        // escaping; there is no expression here to wrap.
+        return expr === null ? (o.slot ?? defaultSlot)(p.slot) : '${escapeRe(' + expr + ')}';
+    })
+        .join('');
+    return `new RegExp(\`${body}\`)`;
+}
+/** Regex SOURCE for one piece of recorded text: literals escaped, slots spliced in as
+ *  `${escapeRe(p.vN)}` (a bound parameter is DATA, so its own metacharacters must not
+ *  become pattern), all of it safe to sit inside a template literal. */
+function patternBody(text, o) {
+    return text
+        .split(SLOT_G)
+        .map((p, i) => {
+        if (i % 2 === 0)
+            return escapeTemplate(reEscape(p));
+        const expr = slotExpr(p, o);
+        return expr === null ? (o.slot ?? defaultSlot)(p) : '${escapeRe(' + expr + ')}';
+    })
+        .join('');
+}
+const reEscape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Source for a matcher over a recorded PAGE LINE - one whose volatile tokens the
+ * STORE already replaced with `{{*}}` (maskVolatile), unlike a locator name, which
+ * arrives verbatim and is masked here by `matcherSource`/`volatileMatcher`.
+ *
+ * Rendered as the literal string it looks like, `{{*}}` can never match anything:
+ * kanboard's `textbox "{{*}} {{*}}"` (a due-date field the app names after the
+ * current date and time) failed on every replay of the compiled spec. So each
+ * wildcard becomes the token shape it stood for - NOT `.*`. The mask is only ever
+ * applied to a clock or calendar token, so the token shape is exactly what was
+ * masked out, and it is what `volatileMatcher` would have produced from the
+ * unmasked line; `.*` would let `textbox "Due date"` satisfy an assertion recorded
+ * for a dated field, which is an assertion looser than the evidence behind it.
+ *
+ * `anchor` mirrors the caller's `exact`: a presence check is a substring match
+ * (Playwright ignores `exact` for a RegExp name, so the anchoring has to carry it),
+ * while the already-in-effect guard reads presence as a reason NOT to act and must
+ * stay line-exact. Null when the text is nothing BUT wildcards: that names no
+ * element at all, and the caller leaves it as an observation.
+ */
+export function maskedMatcherSource(text, o = {}) {
+    if (!text.includes(WILDCARD))
+        return matcherSource(text, o);
+    const parts = text.split(WILDCARD);
+    if (!parts.some((p) => p.trim()))
+        return null;
+    // The shape goes through escapeTemplate too: it is regex source living inside
+    // a template literal, and `\d` there is just "d".
+    const body = parts.map((p) => patternBody(p, o)).join(escapeTemplate(VOLATILE_TOKEN_SHAPE));
+    return `new RegExp(\`${o.anchor ? `^${body}$` : body}\`)`;
+}
+/** Playwright Locator expression for ONE candidate, mirroring makeLocator kind by kind
+ *  (testid -> getByTestId / [attr="v"], role -> getByRole(role,{name,exact:true}), label,
+ *  placeholder, text -> getByText(..,{exact:true}), id/css -> locator(sel), scoped ->
+ *  locator(container,{hasText}).locator(sel), nth -> .nth(n)). Returns null for 'point'
+ *  (not expressible without a runtime). */
+export function candidateSource(c, o = {}) {
+    const page = o.page ?? 'page';
+    let src;
+    switch (c.kind) {
+        case 'testid':
+            src =
+                c.attr === 'data-testid'
+                    ? `${page}.getByTestId(${stringSource(c.value, o)})`
+                    : `${page}.locator(${stringSource(`[${c.attr}=${JSON.stringify(c.value)}]`, o)})`;
+            break;
+        case 'role':
+            src = `${page}.getByRole(${quote(c.role)}, { name: ${matcherSource(c.name, o)}, exact: true })`;
+            break;
+        case 'label':
+            src = `${page}.getByLabel(${matcherSource(c.label, o)})`;
+            break;
+        case 'placeholder':
+            src = `${page}.getByPlaceholder(${matcherSource(c.placeholder, o)})`;
+            break;
+        case 'text':
+            src = `${page}.getByText(${matcherSource(c.text, o)}, { exact: true })`;
+            break;
+        case 'id':
+        case 'css':
+            src = `${page}.locator(${stringSource(c.selector, o)})`;
+            break;
+        case 'scoped':
+            // hasText stays a plain substring match on the container, exactly as
+            // makeLocator passes it: the recorded value names the RECORD.
+            src = `${page}.locator(${stringSource(c.container, o)}, { hasText: ${stringSource(c.hasText, o)} })`;
+            if (c.selector)
+                src += `.locator(${stringSource(c.selector, o)})`;
+            break;
+        case 'point':
+            // markPoint tags the element under the recorded coordinates at replay
+            // time; a plain spec has nothing to tag, so the candidate is dropped
+            // rather than approximated into a selector that names a position.
+            return null;
+    }
+    return c.nth !== undefined ? `${src}.nth(${c.nth})` : src;
+}
+/** The whole chain as ONE expression: candidates ordered by specOf (identity, handles,
+ *  path), joined with .or(), point dropped. When the chain carries identity (a scoped
+ *  candidate with hasText), every non-identity candidate is guarded with
+ *  .filter({ hasText }) so a fallback cannot land on another record - mirrors
+ *  ResolvePolicy.requireIdentity. Returns the source, the candidates that could not be
+ *  expressed, and the hasText guards applied. Multi-line pretty form: one candidate per
+ *  line, `.or(` continuation lines indented by `indent`. */
+/** The chain as an ordered list of expressions, best first, with the identity guards applied. */
+export function candidateSources(chain, o = {}) {
+    const spec = specOf(chain);
+    const ordered = [...spec.identity, ...spec.handles, ...spec.path];
+    const scoped = spec.identity;
+    const guards = [...new Set(scoped.map((c) => c.hasText).filter(Boolean))];
+    const dropped = [];
+    const applied = new Set();
+    const sources = [];
+    for (const c of ordered) {
+        let src = candidateSource(c, o);
+        if (src === null) {
+            dropped.push(c);
+            continue;
+        }
+        if (c.kind !== 'scoped') {
+            // requireIdentity's rule: a value the candidate already carries needs no
+            // guard, everything else must still land on a node bearing the record's
+            // text. Unlike replay there is no exemption for the primary - a spec
+            // re-resolves nothing and has no recovery to fail over to, so a fallback
+            // that would silently work ANOTHER record must instead match nothing and
+            // let the step fail loudly.
+            const expr = JSON.stringify(c);
+            for (const g of guards.filter((v) => !expr.includes(v))) {
+                src += `.filter({ hasText: ${stringSource(g, o)} })`;
+                applied.add(g);
+            }
+        }
+        // A recorded chain routinely names the same element twice - an `id`
+        // candidate and the `css` candidate built from the same selector - and
+        // two identical expressions are two identical resolutions: no extra
+        // coverage, one more line for a reviewer to read past.
+        if (!sources.includes(src))
+            sources.push(src);
+    }
+    return { sources, dropped, identity: [...applied] };
+}
+/** The whole chain as ONE expression: candidates ordered by specOf (identity, handles,
+ *  path), joined with .or(), point dropped. When the chain carries identity (a scoped
+ *  candidate with hasText), every non-identity candidate is guarded with
+ *  .filter({ hasText }) so a fallback cannot land on another record - mirrors
+ *  ResolvePolicy.requireIdentity. Returns the source, the candidates that could not be
+ *  expressed, and the hasText guards applied. Multi-line pretty form: one candidate per
+ *  line, `.or(` continuation lines indented by `indent`.
+ *
+ *  `.or()` is a UNION, so this expresses "any of these", not "the first of
+ *  these that names exactly one element". That is right for a presence check
+ *  and wrong for an action - see the emitter's `pick` helper.
+ */
+export function chainSource(chain, o = {}) {
+    const indent = o.indent ?? '  ';
+    const { sources, dropped, identity } = candidateSources(chain, o);
+    const source = sources.length ? sources[0] + sources.slice(1).map((p) => `
+${indent}.or(${p})`).join('') : '';
+    return { source, dropped, identity };
+}
+//# sourceMappingURL=locators.js.map

package/dist/spec/locators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locators.js","sourceRoot":"","sources":["../../src/spec/locators.ts"],"names":[],"mappings":"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"}

package/dist/spec/lower.js

@@ -0,0 +1,124 @@
+/**
+ * Rebuild one segment as a `Skill`.
+ *
+ * `id` and the procedure fields (template/params/preconditions/steps/derived)
+ * are copied straight from the segment — those are exactly what `toSegment`
+ * (ir.ts) kept, so copying them back is the whole round trip. Everything else
+ * is bookkeeping `toSegment` deliberately drops and this function has to
+ * invent: zeroed stats (a compiled spec carries no replay history), no
+ * fingerprint (the emitted spec never had one to begin with — a live DOM
+ * count vector needs a runtime, not a JSON literal), and a synthetic
+ * provenance naming the spec as its own source rather than a recording
+ * session.
+ *
+ * `seq` is set only when the step's procedure has more than one segment: a
+ * single-segment skill in the wild never carries `seq` (see `Skill.seq` and
+ * `chainOf` in ir.ts, which treats an absent `seq` as "this skill is its own
+ * one-member chain"), and giving every skill a `seq` here would desync from
+ * that. The chain id is the step's FIRST segment's id — stable, unique to
+ * this step (segment ids are unique across a store), and exactly what
+ * `chainOf` needs to find every member back by filtering the origin's skills
+ * on `seq.chain`.
+ */
+function toSkill(spec, step, seg, index, total, now) {
+    const skill = {
+        id: seg.id,
+        origin: spec.origin,
+        template: seg.template,
+        params: seg.params,
+        preconditions: seg.preconditions.requireText
+            ? { urlPattern: seg.preconditions.urlPattern, requireText: seg.preconditions.requireText }
+            : { urlPattern: seg.preconditions.urlPattern },
+        steps: seg.steps,
+        stats: { uses: 0, successes: 0, partial: 0, created: now, failedAtStep: {}, fallthroughs: 0 },
+        status: 'validated',
+        provenance: { session: `spec:${spec.name}`, instruction: step.instruction, created: now },
+    };
+    if (seg.derived)
+        skill.derived = seg.derived;
+    // The goal and the report template it needs travel together, and both are
+    // part of the procedure rather than bookkeeping: a repair that lowered a
+    // spec, replayed it and re-emitted would otherwise drop the "already
+    // satisfied" guard on the way through.
+    if (seg.goal)
+        skill.goal = seg.goal;
+    if (seg.report)
+        skill.reportTemplate = seg.report;
+    if (total > 1)
+        skill.seq = { chain: step.segments[0].id, index, of: total };
+    return skill;
+}
+/**
+ * Rebuild one `FlowStep`. `skill` points at the first segment's id (index 0)
+ * — matching `Skill.seq`'s own doc: "Matching/selection always starts at
+ * index 0" — and `chainOf` walks the rest of the chain from there. A step
+ * whose spec carried no segments (no converged procedure — `flowToSpec`
+ * still exports the shape and warns) gets no `skill` at all, same as a Flow
+ * step that never had one.
+ *
+ * `recorded` and `outputEvidence` are cross-run evidence `SpecStep` never
+ * carried in the first place (ir.ts's `SpecStep` has no field for them), so
+ * they come back empty/absent rather than fabricated — an empty `recorded`
+ * is indistinguishable, to every consumer, from "this run observed nothing
+ * yet", which is the truth for a freshly staged spec.
+ */
+function toFlowStep(spec, step, now, skills) {
+    const segSkills = step.segments.map((seg, i) => toSkill(spec, step, seg, i, step.segments.length, now));
+    skills.push(...segSkills);
+    const flowStep = {
+        id: step.id,
+        instruction: step.instruction,
+        params: step.params,
+        outputs: step.outputs,
+        recorded: {},
+    };
+    if (segSkills.length)
+        flowStep.skill = segSkills[0].id;
+    return flowStep;
+}
+/**
+ * A lifted spec as the Flow + Skill[] the replay/repair code understands.
+ *
+ * Segments become skills that keep their ids, seq (chain = the flow step's
+ * first segment id, index/of from position), preconditions (no fingerprint),
+ * steps, derived, params; stats start at zero, status 'validated' (a
+ * compiled spec is by definition converged), provenance from the spec.
+ *
+ * Mirrors `flowToSpec`'s own ordering exactly (same per-step segment order,
+ * same chain-id choice) so that `flowToSpec(specToFlow(spec).flow, store)`
+ * reproduces `spec` once the returned skills are in a store `flowToSpec` can
+ * read — see `stageForReplay`, and PLAN-self-updating-spec.md's round-trip
+ * invariant.
+ */
+export function specToFlow(spec) {
+    const now = new Date().toISOString();
+    const skills = [];
+    const steps = spec.steps.map((step) => toFlowStep(spec, step, now, skills));
+    const flow = {
+        name: spec.name,
+        origin: spec.origin,
+        startUrl: spec.startUrl,
+        vars: spec.vars,
+        steps,
+        provenance: { session: `spec:${spec.name}`, created: now },
+    };
+    return { flow, skills };
+}
+/**
+ * Write the skills into a store (an isolated temp store is the normal use)
+ * and return the flow, ready for `run`.
+ *
+ * A compiled spec has no store of its own — the spec IS the store, frozen —
+ * so `repair` cannot just point the existing replay/repair machinery at
+ * `~/.sitelooper/skills` (that store may not even have this origin, or may
+ * have moved on since the spec was emitted). Staging into a scratch
+ * `SkillStore` gives that machinery the on-disk shape it already expects
+ * without teaching it a second, spec-native code path.
+ */
+export function stageForReplay(spec, store) {
+    const { flow, skills } = specToFlow(spec);
+    for (const skill of skills)
+        store.put(skill);
+    return flow;
+}
+//# sourceMappingURL=lower.js.map

package/dist/spec/lower.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lower.js","sourceRoot":"","sources":["../../src/spec/lower.ts"],"names":[],"mappings":"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"}