anymorph 0.2.5 → 0.4.0

package/dist/skillpacks/geo/skills/geo-generating-actions/scripts/geo-scaffold.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+	cp,
+	mkdir,
+	readdir,
+	readFile,
+	rm,
+	stat,
+	writeFile,
+} from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const MANAGED_PATHS = [".claude/skills", ".agents/skills", "agent/contracts"];
+const ACTIONS_SCHEMA = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	title: "Anymorph GEO actions artifact",
+	type: "object",
+	required: ["runId", "actions"],
+	properties: {
+		runId: { type: "string" },
+		actions: { type: "array", items: { type: "object" } },
+		artifactPaths: { type: "array", items: { type: "string" } },
+	},
+};
+
+const MEMORY_ITEM_SCHEMA = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	title: "Anymorph GEO memory item",
+	type: "object",
+	required: ["summary"],
+	properties: {
+		summary: { type: "string" },
+		evidence: { type: "array", items: { type: "string" } },
+	},
+};
+
+const mode = process.argv[2];
+const args = parseArgs(process.argv.slice(3));
+
+if (!["init", "sync", "doctor"].includes(mode)) {
+	console.error("Usage: geo-scaffold.mjs <init|sync|doctor> --repo <path> [--skills-source <path>] [--ref <ref>] [--json]");
+	process.exit(2);
+}
+
+try {
+	const result =
+		mode === "doctor"
+			? await doctorGeoScaffold(args)
+			: await applyGeoScaffold(args, { createMemory: mode === "init" });
+
+	if (args.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else if (result.ok) {
+		console.log(`${mode} ok: ${result.repoPath}`);
+		for (const item of result.changed) console.log(`changed: ${item}`);
+	} else {
+		console.error(`${mode} failed: ${result.repoPath}`);
+		for (const problem of result.problems) console.error(`problem: ${problem}`);
+	}
+	process.exit(args.json ? 0 : result.ok ? 0 : 1);
+} catch (err) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (args.json) {
+		console.log(
+			JSON.stringify(
+				{
+					ok: false,
+					repoPath: resolve(args.repo ?? "."),
+					skillsSourceDir: args.skillsSource ? resolve(args.skillsSource) : defaultSkillsSourceDir(),
+					changed: [],
+					problems: [message],
+					manifestHash: null,
+				},
+				null,
+				2,
+			),
+		);
+	} else {
+		console.error(message);
+	}
+	process.exit(1);
+}
+
+function parseArgs(argv) {
+	const parsed = { repo: ".", ref: "local", json: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg === "--json") parsed.json = true;
+		else if (arg === "--repo") parsed.repo = requireValue(argv, ++i, arg);
+		else if (arg === "--skills-source") parsed.skillsSource = requireValue(argv, ++i, arg);
+		else if (arg === "--ref") parsed.ref = requireValue(argv, ++i, arg);
+		else if (arg === "--script-version") parsed.scriptVersion = requireValue(argv, ++i, arg);
+		else if (arg === "--cli-version") parsed.scriptVersion = requireValue(argv, ++i, arg);
+		else throw new Error(`Unknown argument: ${arg}`);
+	}
+	return parsed;
+}
+
+function requireValue(argv, index, flag) {
+	const value = argv[index];
+	if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+	return value;
+}
+
+async function applyGeoScaffold(input, options) {
+	const repoPath = resolve(input.repo ?? ".");
+	const skillsSourceDir = resolveSkillsSourceDir(input.skillsSource);
+	await ensureDirectory(skillsSourceDir);
+	await mkdir(repoPath, { recursive: true });
+
+	const changed = [];
+	const problems = [];
+	const manifestHash = await hashDirectory(skillsSourceDir);
+
+	await syncManagedDirectory(skillsSourceDir, join(repoPath, ".claude", "skills"), changed);
+	await syncManagedDirectory(skillsSourceDir, join(repoPath, ".agents", "skills"), changed);
+	await syncContracts(repoPath, changed);
+	await ensureRunDirs(repoPath, changed);
+	if (options.createMemory) await ensureMemoryFiles(repoPath, changed);
+	await writeSkillpackLock(
+		{
+			repoPath,
+			skillsSourceDir,
+			ref: input.ref ?? "local",
+			manifestHash,
+			scriptVersion: input.scriptVersion ?? null,
+		},
+		changed,
+	);
+
+	return {
+		ok: problems.length === 0,
+		repoPath,
+		skillsSourceDir,
+		changed,
+		problems,
+		manifestHash,
+	};
+}
+
+async function doctorGeoScaffold(input) {
+	const repoPath = resolve(input.repo ?? ".");
+	const skillsSourceDir = resolveSkillsSourceDir(input.skillsSource);
+	await ensureDirectory(skillsSourceDir);
+	const manifestHash = await hashDirectory(skillsSourceDir);
+	const problems = [];
+
+	for (const target of [".claude/skills", ".agents/skills"]) {
+		await compareDirectories(skillsSourceDir, join(repoPath, target), target, problems);
+	}
+	for (const path of [
+		"agent/BRAND.md",
+		"agent/STRATEGY.md",
+		"agent/LEARNINGS.md",
+		"agent/runs/.gitkeep",
+		"agent/archive/.gitkeep",
+		"agent/skillpack.json",
+	]) {
+		if (!(await exists(join(repoPath, path)))) problems.push(`Missing ${path}`);
+	}
+
+	const lock = await readJson(join(repoPath, "agent", "skillpack.json"));
+	if (lock && typeof lock === "object" && lock.manifestHash !== manifestHash) {
+		problems.push("agent/skillpack.json manifestHash does not match current skillpack");
+	}
+
+	return {
+		ok: problems.length === 0,
+		repoPath,
+		skillsSourceDir,
+		changed: [],
+		problems,
+		manifestHash,
+	};
+}
+
+function resolveSkillsSourceDir(explicit) {
+	if (explicit) return resolve(explicit);
+	return defaultSkillsSourceDir();
+}
+
+function defaultSkillsSourceDir() {
+	const scriptDir = dirname(fileURLToPath(import.meta.url));
+	return resolve(scriptDir, "..", "..");
+}
+
+async function syncManagedDirectory(sourceDir, targetDir, changed) {
+	const source = resolve(sourceDir);
+	const target = resolve(targetDir);
+	if (source === target) {
+		return;
+	}
+	if (source.startsWith(`${target}/`)) {
+		throw new Error(`Refusing to sync ${source} into itself at ${target}`);
+	}
+	await rm(target, { recursive: true, force: true });
+	await mkdir(dirname(target), { recursive: true });
+	await cp(source, target, { recursive: true });
+	changed.push(relative(process.cwd(), target) || target);
+}
+
+async function syncContracts(repoPath, changed) {
+	const contractsDir = join(repoPath, "agent", "contracts");
+	await mkdir(contractsDir, { recursive: true });
+	await writeIfChanged(
+		join(contractsDir, "actions.schema.json"),
+		`${JSON.stringify(ACTIONS_SCHEMA, null, 2)}\n`,
+		changed,
+	);
+	await writeIfChanged(
+		join(contractsDir, "memory-item.schema.json"),
+		`${JSON.stringify(MEMORY_ITEM_SCHEMA, null, 2)}\n`,
+		changed,
+	);
+}
+
+async function ensureRunDirs(repoPath, changed) {
+	for (const path of [join(repoPath, "agent", "runs"), join(repoPath, "agent", "archive")]) {
+		await mkdir(path, { recursive: true });
+		await writeIfMissing(join(path, ".gitkeep"), "", changed);
+	}
+}
+
+async function ensureMemoryFiles(repoPath, changed) {
+	await mkdir(join(repoPath, "agent"), { recursive: true });
+	await writeIfMissing(
+		join(repoPath, "agent", "BRAND.md"),
+		"# Brand\n\nInitial local scaffold. Replace with workspace brand context before serious runs.\n",
+		changed,
+	);
+	await writeIfMissing(
+		join(repoPath, "agent", "STRATEGY.md"),
+		"# GEO Strategy\n\n## Current Priorities\n\n- Initial local scaffold.\n",
+		changed,
+	);
+	await writeIfMissing(
+		join(repoPath, "agent", "LEARNINGS.md"),
+		"# Learnings\n\n## Stable Learnings\n\n- Initial local scaffold.\n",
+		changed,
+	);
+}
+
+async function writeSkillpackLock(input, changed) {
+	const sourceCommit = await gitOutput(input.skillsSourceDir, ["rev-parse", "HEAD"]);
+	const lock = {
+		name: "anymorph-geo",
+		source: input.skillsSourceDir,
+		sourceRepo: "opactor-dev/anymorph-geo-skills",
+		requestedRef: input.ref,
+		resolvedCommit: sourceCommit,
+		scriptVersion: input.scriptVersion,
+		manifestHash: input.manifestHash,
+		installedAt: new Date().toISOString(),
+		managedPaths: MANAGED_PATHS,
+	};
+	await writeIfChanged(
+		join(input.repoPath, "agent", "skillpack.json"),
+		`${JSON.stringify(lock, null, 2)}\n`,
+		changed,
+	);
+}
+
+async function compareDirectories(sourceDir, targetDir, displayPrefix, problems) {
+	const sourceFiles = await listFiles(sourceDir);
+	const targetFiles = await listFiles(targetDir);
+	const targetSet = new Set(targetFiles);
+	for (const file of sourceFiles) {
+		const source = await readFile(join(sourceDir, file), "utf8");
+		const targetPath = join(targetDir, file);
+		if (!(await exists(targetPath))) {
+			problems.push(`Missing ${displayPrefix}/${file}`);
+			continue;
+		}
+		const target = await readFile(targetPath, "utf8");
+		if (source !== target) problems.push(`Drifted ${displayPrefix}/${file}`);
+		targetSet.delete(file);
+	}
+	for (const extra of targetSet) problems.push(`Extra managed file ${displayPrefix}/${extra}`);
+}
+
+async function hashDirectory(dir) {
+	const files = await listFiles(dir);
+	const hash = createHash("sha256");
+	for (const file of files) {
+		hash.update(file);
+		hash.update("\0");
+		hash.update(await readFile(join(dir, file)));
+		hash.update("\0");
+	}
+	return `sha256:${hash.digest("hex")}`;
+}
+
+async function listFiles(dir, base = "") {
+	let entries;
+	try {
+		entries = await readdir(join(dir, base), { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const files = [];
+	for (const entry of entries) {
+		const name = String(entry.name);
+		const path = base ? `${base}/${name}` : name;
+		if (entry.isDirectory()) files.push(...(await listFiles(dir, path)));
+		else if (entry.isFile()) files.push(path);
+	}
+	return files.sort();
+}
+
+async function writeIfMissing(path, content, changed) {
+	if (await exists(path)) return;
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, content);
+	changed.push(relative(process.cwd(), path) || path);
+}
+
+async function writeIfChanged(path, content, changed) {
+	const current = await readFile(path, "utf8").catch(() => null);
+	if (current === content) return;
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, content);
+	changed.push(relative(process.cwd(), path) || path);
+}
+
+async function readJson(path) {
+	const raw = await readFile(path, "utf8").catch(() => null);
+	if (!raw) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+
+async function gitOutput(cwd, args) {
+	try {
+		const { stdout } = await execFileAsync("git", args, { cwd });
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+
+async function ensureDirectory(path) {
+	const s = await stat(path);
+	if (!s.isDirectory()) throw new Error(`${path} is not a directory`);
+}
+
+async function exists(path) {
+	return stat(path)
+		.then(() => true)
+		.catch(() => false);
+}

package/dist/skillpacks/geo/skills/geo-generating-actions/scripts/geo.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+
+const legacyCommand = process.argv[2];
+const legacyArgs = process.argv.slice(3);
+
+const commandMap = new Map([
+	["materialize", "submit"],
+	["check", "doctor"],
+	["sync", "doctor"],
+]);
+
+if (!legacyCommand || ["-h", "--help", "help"].includes(legacyCommand)) {
+	usage();
+	process.exit(0);
+}
+
+if (legacyArgs.includes("--repo")) {
+	console.error(
+		"`--repo` is no longer supported. Run `anymorph` from the tenant repo root instead.",
+	);
+	process.exit(2);
+}
+
+const command = commandMap.get(legacyCommand) ?? legacyCommand;
+const args = legacyArgs.filter((arg) => !arg.startsWith("--repo="));
+if (legacyCommand === "sync") args.unshift("--fix");
+
+console.error(
+	"`geo.mjs` is deprecated. Use the top-level Anymorph CLI: " +
+		`anymorph ${[command, ...args].join(" ")}`.trim(),
+);
+
+const child = spawn("anymorph", [command, ...args], {
+	stdio: "inherit",
+	env: process.env,
+});
+
+child.on("exit", (code, signal) => {
+	if (signal) {
+		process.kill(process.pid, signal);
+		return;
+	}
+	process.exit(code ?? 1);
+});
+
+child.on("error", (err) => {
+	console.error(`Could not run \`anymorph\`: ${err.message}`);
+	process.exit(1);
+});
+
+function usage() {
+	console.error(`Usage:
+  anymorph login
+  anymorph logout
+  anymorph status
+  anymorph workspaces
+  anymorph init
+  anymorph doctor
+  anymorph doctor --fix
+  anymorph prepare <workspaceId>
+  anymorph validate <runId>
+  anymorph submit <runId>
+  anymorph intents <runId>
+  anymorph run-status <runId>`);
+}

package/dist/skillpacks/geo/skills/geo-initializing-strategy/references/foundation-diagnosis.md

@@ -37,7 +37,7 @@ Use these DFS fields:
 
 Do not use DataForSEO Backlinks API as a substitute for owned-site internal-link evidence. Use DataForSEO On-Page only.
 
-Do not claim a page is an in-content hub from DFS alone. DFS On-Page can show internal edges and target status, but not guaranteed nav/footer/content placement. For true in-content hub claims, corroborate with CMS source or page HTML via `get_page_source_code`, `get_page_content`, or summarized scrape.
+Do not claim a page is an in-content hub from DFS alone. DFS On-Page can show internal edges and target status, but not guaranteed nav/footer/content placement. For true in-content hub claims, corroborate with page content or page HTML via `get_page_content` or summarized scrape.
 
 Use Ahrefs only as optional enrichment for crawl and in-content internal-link evidence. For internal-link hubs, filter to in-content, dofollow links when the endpoint supports it. If Ahrefs returns "API units limit reached", times out, fails auth, or is unavailable, stop calling Ahrefs and continue with DataForSEO On-Page + owned-source evidence.
 

package/dist/skillpacks/geo/skills/geo-local-setup/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: geo-local-setup
+description: Use when setting up, checking, repairing, or preparing a tenant repo for local Anymorph GEO work.
+---
+
+# GEO Local Setup
+
+Use this skill before local GEO action generation in a tenant repo.
+
+## CLI
+
+Use the top-level `anymorph` CLI. Run commands from the tenant repo root.
+
+## Setup
+
+Run these from the tenant repo root:
+
+```bash
+anymorph status
+anymorph login
+anymorph init
+anymorph doctor
+```
+
+If credentials are missing, authenticated commands start device login
+automatically. Use `login` directly when you want to authenticate first.
+For non-interactive runs, set `ANYMORPH_ACCESS_TOKEN` and optionally
+`ANYMORPH_API_URL`.
+
+`init` installs managed skills, contracts, run folders, and missing memory files.
+`doctor` reports exact missing, extra, or drifted managed files. Use
+`doctor --fix` to repair managed files without touching memory or run artifacts.
+
+To compare against a known source checkout instead of the installed copy:
+
+```bash
+anymorph doctor --skills-source /path/to/anymorph-geo-skills/skills
+```
+
+## Prepare
+
+```bash
+anymorph status
+anymorph workspaces
+anymorph prepare <workspaceId>
+```
+
+After the agent writes `actions.json`:
+
+```bash
+anymorph validate {runId}
+git add agent/runs/{runId} agent/STRATEGY.md agent/LEARNINGS.md
+git commit -m "chore: add geo strategy run {runId}"
+git push origin main
+anymorph submit {runId}
+```
+
+`submit` registers or updates the backend run and immediately materializes it
+in Dashboard. There is no separate approve step.
+A submitted run is immutable: once it is `executed`, re-submitting the same
+`runId` (even with an edited `actions.json`) is a no-op. To add or change
+actions, run a fresh `prepare` for a new `runId` and submit that new run.
+For commerce workspaces, `validate` requires every `geo_page` create action to
+include `target.targetProductIds` from the prepared product files.
+
+The `anymorph` CLI owns local GEO setup, prepare, validate, and submit.

package/dist/skillpacks/geo/skills/geo-local-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Local Setup"
+  short_description: "Set up and verify a tenant repo for local GEO work."
+  default_prompt: "Use $geo-local-setup to set up or check this tenant repo for local GEO work."

package/dist/skillpacks/geo/skills/geo-page-writer/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: geo-page-writer
+description: Use when writing or updating the actual MDX for an Anymorph-managed GEO page in a CMS tenant repo after a geo_page action or generated-page opportunity has been selected.
+---
+
+# GEO Page Writer
+
+Use this skill to write or revise a real CMS MDX page for a selected
+`geo_page` action. This is an execution skill, not a strategy-planning skill.
+
+## Scope
+
+Write or update:
+
+- A tenant repo MDX page for a generated GEO page.
+- The supporting page-writer evidence artifacts under `agent/page-writer/`.
+
+Do not:
+
+- Write `actions.json`.
+- Submit GEO strategy runs.
+- Replace the backend CMS generation pipeline.
+- Invent claims, product facts, prices, image URLs, testimonials, quotes, or
+  source names.
+
+## References
+
+Read these references before writing:
+
+- `references/research.md` for source collection, Exa Deep Search, KB search,
+  image search, and source-pack rules.
+- `references/writing.md` for MDX structure, frontmatter, components, images,
+  CTA, and GEO writing rules.
+- `references/validation.md` for agent-owned brand and fact validation plus
+  script-backed MDX static checks.
+
+## Workflow
+
+1. Identify the selected `geo_page` action from `agent/runs/{runId}/actions.json`.
+2. Collect page sources:
+
+```bash
+node .agents/skills/geo-page-writer/scripts/collect-page-sources.mjs all \
+  --run-id <runId> \
+  --action-id <actionId> \
+  --workspace <workspace-id-or-domain>
+```
+
+Use `.claude/skills/...` instead of `.agents/skills/...` when running under
+Claude Code.
+
+3. Read `agent/page-writer/{runId}/{actionId}/sources/source-pack.json`.
+4. Write or edit the MDX manually using the source pack and `references/writing.md`.
+5. Self-review brand and fact claims with `references/validation.md`.
+6. Run the static MDX checker:
+
+```bash
+node .agents/skills/geo-page-writer/scripts/check-page-mdx.mjs \
+  --file <path/to/page.mdx> \
+  --sources agent/page-writer/<runId>/<actionId>/sources/source-pack.json
+```
+
+7. Fix every error. Review warnings before commit.
+
+## Artifact Contract
+
+Write page-writer artifacts here:
+
+```text
+agent/page-writer/{runId}/{actionId}/
+  sources/
+    exa-research.md
+    exa-response.json
+    kb-results.json
+    image-results.json
+    source-pack.json
+  checks/
+    mdx-static.json
+```
+
+Commit the MDX and relevant `agent/page-writer/...` artifacts together.

package/dist/skillpacks/geo/skills/geo-page-writer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Page Writer"
+  short_description: "Write and validate real CMS MDX for selected GEO page actions."
+  default_prompt: "Use $geo-page-writer to collect sources, write the GEO page MDX, and run static MDX validation."

package/dist/skillpacks/geo/skills/geo-page-writer/references/research.md

@@ -0,0 +1,61 @@
+# Research
+
+The research phase builds the source pack used to write the page. It does not
+write the MDX.
+
+## Source Order
+
+Use sources in this order:
+
+1. Selected `geo_page` action and run context.
+2. Tenant workspace KB / living document.
+3. Product catalog or action `targetProductIds`.
+4. Exa Deep Search for external evidence.
+5. Image search for existing brand assets.
+
+Prefer first-party and workspace facts over external summaries. Use external
+research to fill market, comparison, definition, and citation gaps.
+
+## Exa Deep Search
+
+`collect-page-sources.mjs exa` uses Exa `/search` with `type:
+"deep-reasoning"`. Exa's older `/research/v1` API is deprecated, so do not use
+it for new work.
+
+The Exa result is a research input, not page copy. Treat its synthesized answer
+as a draft finding that still needs source-aware judgment.
+
+## KB Search
+
+Use KB search for brand-specific facts:
+
+- product positioning
+- process and methodology
+- pricing or packaging claims
+- company history
+- differentiators
+- support, FAQ, and policy details
+
+If KB search is unavailable, mark the missing query in the source pack and avoid
+brand-specific factual claims that need that evidence.
+
+## Image Search
+
+Use image search only for existing workspace assets. Do not generate images in
+this skill.
+
+Every MDX image URL should come from:
+
+- the source pack image results
+- product catalog image inputs
+- an existing tenant asset already present in the MDX/repo
+
+## Source Pack Rules
+
+The source pack must make writing decisions auditable:
+
+- Keep source URLs and titles.
+- Keep KB snippets separate from external web sources.
+- Keep image results separate from factual sources.
+- Record failures instead of silently omitting a source class.
+- Do not promote a source into a claim unless the source actually supports it.