4lothru 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ndivho Makhuvha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# 4lothru
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install the SDK and CLI from one self-contained package:
+
+```bash
+npm install 4lothru
+```
+
+Initialize the browser SDK once at app startup:
+
+```ts
+import { Trail } from "4lothru";
+
+Trail.init();
+```
+
+The CLI is available as `4lothru`:
+
+```bash
+npx 4lothru validate
+npx 4lothru build
+npx 4lothru preview
+```

package/bin/4lothru.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.js

@@ -0,0 +1,386 @@
+// ../cli/src/cli.ts
+import { Command } from "commander";
+
+// ../cli/src/validate.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import path from "path";
+
+// ../guide-schema/dist/index.js
+import { z } from "zod";
+import { z as z2 } from "zod";
+import { z as z3 } from "zod";
+import { parse as parseYamlText } from "yaml";
+var TargetSchema = z.object({
+  testId: z.string().min(1).optional(),
+  role: z.string().min(1).optional(),
+  name: z.string().min(1).optional(),
+  label: z.string().min(1).optional(),
+  text: z.string().min(1).optional(),
+  selector: z.string().min(1).optional()
+}).strict().superRefine((value, ctx) => {
+  const hasStrategy = !!value.testId || !!value.role && !!value.name || !!value.label || !!value.text || !!value.selector;
+  if (!hasStrategy) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Target must specify at least one of testId, role+name, label, text, or selector."
+    });
+  }
+  if (value.role && !value.name) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["name"], message: "A role target also requires a name." });
+  }
+  if (value.name && !value.role) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["role"], message: "A name target also requires a role." });
+  }
+});
+var id = z2.string().min(1);
+var instruction = z2.string().min(1);
+var autoAdvance = z2.boolean().optional();
+var ClickStepSchema = z2.object({ id, action: z2.literal("click"), target: TargetSchema, instruction, autoAdvance }).strict();
+var InputStepSchema = z2.object({
+  id,
+  action: z2.literal("input"),
+  target: TargetSchema,
+  value: z2.string(),
+  instruction,
+  autoAdvance
+}).strict();
+var SelectStepSchema = z2.object({
+  id,
+  action: z2.literal("select"),
+  target: TargetSchema,
+  value: z2.string(),
+  instruction,
+  autoAdvance
+}).strict();
+var VerifyStepSchema = z2.object({ id, action: z2.literal("verify"), target: TargetSchema, instruction }).strict();
+var NavigateStepSchema = z2.object({ id, action: z2.literal("navigate"), url: z2.string().min(1), instruction }).strict();
+var WaitStepSchema = z2.object({
+  id,
+  action: z2.literal("wait"),
+  target: TargetSchema.optional(),
+  timeoutMs: z2.number().int().positive().optional(),
+  instruction
+}).strict();
+var GuideStepSchema = z2.discriminatedUnion("action", [
+  ClickStepSchema,
+  InputStepSchema,
+  SelectStepSchema,
+  VerifyStepSchema,
+  NavigateStepSchema,
+  WaitStepSchema
+]);
+var placementFields = {
+  before: z2.string().min(1).optional(),
+  after: z2.string().min(1).optional()
+};
+var AuthorGuideStepSchema = z2.discriminatedUnion("action", [
+  ClickStepSchema.extend(placementFields),
+  InputStepSchema.extend(placementFields),
+  SelectStepSchema.extend(placementFields),
+  VerifyStepSchema.extend(placementFields),
+  NavigateStepSchema.extend(placementFields),
+  WaitStepSchema.extend(placementFields)
+]);
+var GuideSchema = z3.object({
+  id: z3.string().min(1),
+  title: z3.string().min(1),
+  application: z3.string().min(1),
+  release: z3.string().min(1),
+  start: z3.object({ url: z3.string().min(1) }).strict(),
+  steps: z3.array(GuideStepSchema).min(1, "A guide must contain at least one step.")
+}).passthrough();
+var AuthorGuideSchema = z3.object({
+  id: z3.string().min(1),
+  title: z3.string().min(1),
+  application: z3.string().min(1),
+  release: z3.string().min(1),
+  start: z3.object({ url: z3.string().min(1) }).strict(),
+  extends: z3.string().min(1).optional(),
+  steps: z3.array(AuthorGuideStepSchema).min(1, "A guide must contain at least one step.")
+}).passthrough().superRefine((guide, context) => {
+  guide.steps.forEach((step, index) => {
+    const hasBefore = step.before !== void 0;
+    const hasAfter = step.after !== void 0;
+    if (hasBefore && hasAfter) {
+      context.addIssue({
+        code: z3.ZodIssueCode.custom,
+        path: ["steps", index],
+        message: "An extension step must use either before or after, not both."
+      });
+    }
+    if (guide.extends && !hasBefore && !hasAfter) {
+      context.addIssue({
+        code: z3.ZodIssueCode.custom,
+        path: ["steps", index],
+        message: "An extension step must specify before or after."
+      });
+    }
+    if (!guide.extends && (hasBefore || hasAfter)) {
+      context.addIssue({
+        code: z3.ZodIssueCode.custom,
+        path: ["steps", index],
+        message: "before and after are only valid on a guide with extends."
+      });
+    }
+  });
+});
+function formatPath(path3) {
+  if (path3.length === 0) return "(root)";
+  let out = "";
+  for (const segment of path3) {
+    if (typeof segment === "number") {
+      out += `[${segment}]`;
+    } else {
+      out += out ? `.${segment}` : segment;
+    }
+  }
+  return out;
+}
+function issuesFromZodError(error) {
+  return error.issues.map((issue) => {
+    const path3 = formatPath(issue.path);
+    const lastSegment = issue.path[issue.path.length - 1];
+    if (lastSegment === "target" && issue.code === "invalid_type") {
+      return { path: path3, message: "Target is required." };
+    }
+    return { path: path3, message: issue.message };
+  });
+}
+function parseAuthorData(raw) {
+  const result = AuthorGuideSchema.safeParse(raw);
+  if (!result.success) {
+    return { success: false, issues: issuesFromZodError(result.error) };
+  }
+  return { success: true, guide: result.data };
+}
+function parseAuthorGuideYaml(yamlText) {
+  let raw;
+  try {
+    raw = parseYamlText(yamlText);
+  } catch (error) {
+    return {
+      success: false,
+      issues: [
+        { path: "(yaml)", message: error instanceof Error ? error.message : "Invalid YAML." }
+      ]
+    };
+  }
+  return parseAuthorData(raw);
+}
+function withoutPlacement(step) {
+  const { before: _before, after: _after, ...runtimeStep } = step;
+  return runtimeStep;
+}
+function duplicateStepIssue(steps) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    if (ids.has(step.id)) {
+      return { path: "steps", message: `Duplicate step id: ${step.id}.` };
+    }
+    ids.add(step.id);
+  }
+  return void 0;
+}
+function runtimeGuideData(guide, steps) {
+  const { extends: _extends, steps: _steps, ...runtimeGuide } = guide;
+  return { ...runtimeGuide, steps };
+}
+function resolveGuide(guide, guidesById, resolving = /* @__PURE__ */ new Set()) {
+  var _a;
+  if (resolving.has(guide.id)) {
+    return { success: false, issues: [{ path: "extends", message: "Guide inheritance cycle detected." }] };
+  }
+  if (!guide.extends) {
+    const steps2 = guide.steps.map(withoutPlacement);
+    const duplicateIssue2 = duplicateStepIssue(steps2);
+    if (duplicateIssue2) return { success: false, issues: [duplicateIssue2] };
+    const parsed2 = GuideSchema.safeParse(runtimeGuideData(guide, steps2));
+    return parsed2.success ? { success: true, guide: parsed2.data } : { success: false, issues: parsed2.error.issues.map((issue) => ({ path: issue.path.join("."), message: issue.message })) };
+  }
+  const base = guidesById.get(guide.extends);
+  if (!base) {
+    return { success: false, issues: [{ path: "extends", message: `Base guide not found: ${guide.extends}.` }] };
+  }
+  if (guide.release !== base.release || guide.application !== base.application) {
+    return {
+      success: false,
+      issues: [{ path: "extends", message: "An extension must match its base guide's release and application." }]
+    };
+  }
+  const nextResolving = new Set(resolving);
+  nextResolving.add(guide.id);
+  const baseResult = resolveGuide(base, guidesById, nextResolving);
+  if (!baseResult.success) return baseResult;
+  const steps = [...baseResult.guide.steps];
+  for (const extensionStep of guide.steps) {
+    const anchorId = (_a = extensionStep.before) != null ? _a : extensionStep.after;
+    const anchorIndex = steps.findIndex((step) => step.id === anchorId);
+    if (anchorIndex === -1) {
+      return { success: false, issues: [{ path: "steps", message: `Anchor step not found: ${anchorId}.` }] };
+    }
+    steps.splice(extensionStep.before ? anchorIndex : anchorIndex + 1, 0, withoutPlacement(extensionStep));
+  }
+  const duplicateIssue = duplicateStepIssue(steps);
+  if (duplicateIssue) return { success: false, issues: [duplicateIssue] };
+  const parsed = GuideSchema.safeParse(runtimeGuideData(guide, steps));
+  return parsed.success ? { success: true, guide: parsed.data } : { success: false, issues: parsed.error.issues.map((issue) => ({ path: issue.path.join("."), message: issue.message })) };
+}
+
+// ../cli/src/validate.ts
+var REPO_ROOT = process.cwd();
+var GUIDES_ROOT = path.join(REPO_ROOT, "guides", "releases");
+function discoverGuides(guidesRoot = GUIDES_ROOT) {
+  if (!existsSync(guidesRoot)) return [];
+  const guides = [];
+  const releases = readdirSync(guidesRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  for (const release of releases) {
+    const releaseDir = path.join(guidesRoot, release.name);
+    const files = readdirSync(releaseDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml"));
+    for (const file of files.sort()) {
+      guides.push({ release: release.name, file, filePath: path.join(releaseDir, file) });
+    }
+  }
+  return guides;
+}
+function resolveDiscoveredGuides(guidesRoot = GUIDES_ROOT) {
+  const parsed = discoverGuides(guidesRoot).map((source) => ({
+    source,
+    result: parseAuthorGuideYaml(readFileSync(source.filePath, "utf-8"))
+  }));
+  const releases = /* @__PURE__ */ new Map();
+  for (const entry of parsed) {
+    const release = releases.get(entry.source.release) ?? [];
+    release.push(entry);
+    releases.set(entry.source.release, release);
+  }
+  const results = [];
+  for (const [release, entries] of releases) {
+    const guidesById = /* @__PURE__ */ new Map();
+    const duplicateIds = /* @__PURE__ */ new Set();
+    for (const { result } of entries) {
+      if (!result.success) continue;
+      if (guidesById.has(result.guide.id)) duplicateIds.add(result.guide.id);
+      else guidesById.set(result.guide.id, result.guide);
+    }
+    for (const { source, result } of entries) {
+      if (!result.success) {
+        results.push({ source, success: false, issues: result.issues });
+      } else if (duplicateIds.has(result.guide.id)) {
+        results.push({
+          source,
+          success: false,
+          issues: [{ path: "id", message: `Duplicate guide id in release ${release}: ${result.guide.id}.` }]
+        });
+      } else {
+        const resolved = resolveGuide(result.guide, guidesById);
+        results.push(
+          resolved.success ? { source, success: true, guide: resolved.guide } : { source, success: false, issues: resolved.issues }
+        );
+      }
+    }
+  }
+  return results;
+}
+function validateGuides() {
+  const results = resolveDiscoveredGuides().map((result) => {
+    const file = `${result.source.release}/${result.source.file}`;
+    return result.success ? { file, success: true } : { file, success: false, issues: result.issues };
+  });
+  return { results };
+}
+function runValidate() {
+  const { results } = validateGuides();
+  if (results.length === 0) {
+    console.log("No guides found under guides/releases/.");
+    return;
+  }
+  const failures = results.filter((r) => !r.success);
+  for (const result of results) {
+    if (result.success) {
+      console.log(`\u2713 ${result.file}`);
+    }
+  }
+  if (failures.length > 0) {
+    for (const failure of failures) {
+      console.log("");
+      console.log(`\u2717 ${failure.file}`);
+      console.log("");
+      for (const issue of failure.issues ?? []) {
+        console.log(`${issue.path}:`);
+        console.log(issue.message);
+      }
+    }
+    console.log("");
+    console.error(`${failures.length} of ${results.length} guide(s) invalid.`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log("");
+  console.log(`${results.length} guides valid.`);
+}
+
+// ../cli/src/build.ts
+import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "fs";
+import path2 from "path";
+var OUTPUT_ROOT = path2.join(REPO_ROOT, "dist", "releases");
+function runBuild(options = {}) {
+  const outputRoot = options.outputRoot ?? OUTPUT_ROOT;
+  const guidesRoot = options.guidesRoot;
+  const guides = resolveDiscoveredGuides(guidesRoot);
+  if (guides.length === 0) {
+    rmSync(outputRoot, { recursive: true, force: true });
+    console.log(`No guides found under ${guidesRoot ?? "guides/releases/"}.`);
+    return;
+  }
+  const failures = guides.filter((result) => !result.success);
+  if (failures.length > 0) {
+    for (const result of failures) {
+      console.error(`\u2717 ${result.source.release}/${result.source.file}`);
+      for (const issue of result.issues) {
+        console.error(`  ${issue.path}: ${issue.message}`);
+      }
+    }
+    console.log("");
+    console.error("Build failed: one or more guides are invalid.");
+    process.exitCode = 1;
+    return;
+  }
+  mkdirSync(path2.dirname(outputRoot), { recursive: true });
+  const stagingRoot = mkdtempSync(`${outputRoot}.tmp-`);
+  for (const result of guides) {
+    if (!result.success) continue;
+    const outDir = path2.join(stagingRoot, result.source.release);
+    mkdirSync(outDir, { recursive: true });
+    const outFile = path2.join(outDir, `${result.guide.id}.json`);
+    writeFileSync(outFile, JSON.stringify(result.guide, null, 2));
+    console.log(`\u2713 built ${result.source.release}/${path2.basename(outFile)}`);
+  }
+  rmSync(outputRoot, { recursive: true, force: true });
+  renameSync(stagingRoot, outputRoot);
+  console.log("");
+  console.log(`Built ${guides.length} guide(s) to ${outputRoot}.`);
+}
+
+// ../cli/src/preview.ts
+import { spawn } from "child_process";
+function runPreview() {
+  console.log("Starting local preview server...");
+  console.log("Example: http://localhost:5173/g/2026.08.26/PAY-1245");
+  console.log("");
+  const child = spawn("pnpm", ["--filter", "@4lothru/viewer", "dev"], {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  child.on("exit", (code) => {
+    process.exitCode = code ?? 0;
+  });
+}
+
+// ../cli/src/cli.ts
+var program = new Command();
+program.name("4lothru").description("4lothru CLI").version("0.1.0");
+program.command("validate").description("Validate all YAML guides under guides/releases/").action(() => runValidate());
+program.command("build").description("Convert YAML guides into static JSON assets under dist/releases/").action(() => runBuild());
+program.command("preview").description("Start a local preview server for the viewer").action(() => runPreview());
+program.parse(process.argv);