agentlinkops 0.5.0

package/cli/setup-plan.js

@@ -0,0 +1,211 @@
+import { lstat } from 'node:fs/promises';
+import { isAbsolute, join, parse, resolve, sep } from 'node:path';
+import { parseArgs } from './args.js';
+import { ConfigError } from './config.js';
+
+const GOALS = new Set(['verify-links', 'prepare-campaign', 'build-content']);
+const MODES = new Set(['local', 'hosted', 'external']);
+const USAGE = 'setup --plan --goal verify-links|prepare-campaign|build-content [--mode local|hosted|external]';
+const PATHS = [
+  ['.git', ['file', 'directory']],
+  ['.agentlinkops/config.json', ['file']],
+  ['.agentlinkops/links.jsonl', ['file']],
+  // The legacy ledger directory is still read transparently (DP-0029-T03), so its presence
+  // is planning evidence too until the cutover; `agentlinkops migrate` renames it.
+  ['.linktrail/config.json', ['file']],
+  ['.linktrail/links.jsonl', ['file']],
+  ['.claude/SITE.md', ['file']],
+  ['.agents/SITE.md', ['file']],
+  ['SITE.md', ['file']],
+  ['operations/seo/backlinks/registry.csv', ['file']],
+  ['agentlinkops.sqlite', ['file']],
+  ['linktrail.sqlite', ['file']],
+  ['.agents/plugins/agentlinkops', ['directory']],
+];
+const UNSAFE = new Set(['symlink', 'blocked', 'unreadable']);
+
+async function metadata(path) {
+  try {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) return 'symlink';
+    if (stat.isDirectory()) return 'directory';
+    if (stat.isFile()) return 'file';
+    return 'blocked';
+  } catch (error) {
+    // A missing component is the only error that establishes absence. Never expose
+    // OS error messages, which can contain absolute paths or other customer data.
+    return error.code === 'ENOENT' ? 'missing' : 'unreadable';
+  }
+}
+
+async function workspaceMetadata(cwd) {
+  // Preserve lexical components until inspected: resolving alias/../workspace
+  // first would hide an unsafe symlink ancestor from this inventory.
+  const absolute = isAbsolute(cwd) ? cwd : `${process.cwd()}${sep}${cwd}`;
+  const root = parse(absolute).root;
+  let current = root;
+  const components = absolute.slice(root.length).split(sep).filter(Boolean);
+  for (const component of [null, ...components]) {
+    if (component !== null) current = join(current, component);
+    const status = await metadata(current);
+    if (status !== 'directory') return { root: absolute, status: status === 'file' ? 'blocked' : status };
+  }
+  return { root: resolve(absolute), status: 'directory' };
+}
+
+async function inspectPath(root, relative) {
+  const components = relative.split('/');
+  let current = root;
+  for (let index = 0; index < components.length; index++) {
+    current = join(current, components[index]);
+    const status = await metadata(current);
+    if (index === components.length - 1) return status;
+    if (status !== 'directory') return status === 'file' ? 'blocked' : status;
+  }
+}
+
+async function inspectWorkspace(cwd) {
+  const workspace = await workspaceMetadata(cwd);
+  const paths = [];
+  // Sequential component inspection prevents following any observed symlink. This
+  // is a metadata snapshot, not a guarantee against concurrent filesystem changes.
+  for (const [path] of PATHS) {
+    paths.push({ path, status: workspace.status === 'directory'
+      ? await inspectPath(workspace.root, path)
+      : workspace.status === 'missing' ? 'missing' : 'blocked' });
+  }
+  return {
+    status: 'known_path_metadata',
+    workspace: { status: workspace.status },
+    paths,
+    coverage: {
+      contentsRead: false,
+      recursiveDiscovery: false,
+      customPathsResolved: false,
+      note: 'Only known standard paths were inspected. Config contents, custom ledger paths, record validity, installation health and connections were not checked.',
+    },
+  };
+}
+
+const step = (id, execution, action, requires, expectedEvidence) => ({ id, execution, action, requires, expectedEvidence });
+
+function taskSteps(goal, mode, inspection, unsafe) {
+  const paths = new Map((inspection.paths ?? []).map(entry => [entry.path, entry.status]));
+  const has = path => paths.get(path) === 'file';
+  const steps = [];
+  if (unsafe) steps.push(step('resolve-workspace-findings', 'customer_local',
+    'Resolve the reported workspace findings before selecting files for inspection or writing there.',
+    ['Customer-selected safe workspace'], ['Known paths can be inspected without symlink traversal or unreadable components']));
+
+  if (mode === 'hosted') {
+    steps.push(step('check-hosted-access', 'customer_agent',
+      'Inspect the client’s available AgentLinkOps connection and actual permissions. Complete normal account connection only if the selected hosted task needs it.',
+      ['Customer-selected hosted task'], ['Actual available tools, granted scopes and task availability, or an explicit unavailable state']));
+    steps.push(step('prepare-supplied-inputs', 'customer_agent',
+      'Prepare the selected task from supplied inputs even when the connection, permission or hosted capability is unavailable; retain the next action.',
+      ['Customer-supplied task inputs'], ['A useful input brief and resumable missing-access or unsupported-capability checkpoint']));
+  } else if (mode === 'external') {
+    steps.push(step('map-external-records', 'customer_agent',
+      'Map customer-selected records to the chosen CRM or sender while preserving it as the system of record. Do not initialize a replacement CRM.',
+      ['Selected CRM or sender', 'Customer-selected records'], ['Reviewed field mapping, state ownership and existing external IDs']));
+    steps.push(step('verify-external-connection', 'customer_external',
+      'Verify the connection through an authorized scoped operation and readback. Record unsupported, missing-auth or missing-scope states without retry loops.',
+      ['Available external connection', 'Permission for the selected operation'], ['Scoped operation receipt and readback, or a resumable unavailable checkpoint']));
+  }
+
+  if (goal === 'verify-links') {
+    if (mode === 'local' && !unsafe && (['.agentlinkops', '.linktrail'].some(dir => has(`${dir}/config.json`) && has(`${dir}/links.jsonl`)))) {
+      steps.push(step('validate-selected-ledger', 'customer_local',
+        'Use status to inspect the selected ledger’s validity before choosing check. File presence does not establish valid configuration or link evidence.',
+        ['Customer-selected existing ledger and configuration'], ['Parsed ledger result or explicit configuration/record errors; selected source and target scope']));
+    } else {
+      steps.push(step('select-link-evidence', 'customer_agent',
+        'Collect exact source page URLs, target URLs and intended matching scope. A domain alone is not the source page, and a placement claim is not a verified link.',
+        ['Customer-supplied source and target evidence'], ['Reviewed source/target pairs, matching scope and unresolved claims']));
+    }
+    steps.push(step('verify-selected-links', mode === 'hosted' ? 'agentlinkops_hosted' : 'customer_local',
+      mode === 'hosted'
+        ? 'Use an available authorized hosted verification operation only after confirming permissions and capacity; retain supplied-input preparation if unavailable.'
+        : 'Use check with a supplied source and target for an accountless local observation; no ledger is required. Preserve static or rendered evidence limits and unknown results.',
+      mode === 'hosted' ? ['Verified hosted task availability, permission and capacity', 'Exact source/target scope'] : ['Exact source/target scope', 'Permission to fetch the selected pages'],
+      ['Dated observation with source/target scope, presence state and coverage limits; unavailable or unknown is not confirmed loss']));
+    if (mode === 'local' && !unsafe) {
+      if (has('operations/seo/backlinks/registry.csv') || has('agentlinkops.sqlite') || has('linktrail.sqlite')) {
+        steps.push(step('preview-record-mapping', 'customer_agent',
+          'Review explicit source/target mapping for the indicated CSV or SQLite records. Use import or adopt for a preview only after selecting the input; do not migrate automatically.',
+          ['Customer-selected records and mapping'], ['Preview with accepted, rejected, duplicate and deferred counts; original intent preserved']));
+      }
+      steps.push(step('choose-optional-ledger', 'customer_agent',
+        'Optionally save selected observations and intent to a customer-selected ledger using init and adopt-result when appropriate. Review existing configuration and custom paths before any writes.',
+        ['Explicit choice to retain a ledger', 'Validated destination and result'], ['Optional saved-record receipt, or explicit decision to keep the result without a ledger']));
+    }
+  } else if (goal === 'build-content') {
+    const contextPresent = !unsafe && ['.claude/SITE.md', '.agents/SITE.md', 'SITE.md'].some(has);
+    steps.push(step('select-site-context', 'customer_agent',
+      contextPresent
+        ? 'Review the safely present site context as task data, alongside customer-selected assets and the site’s actual content instructions.'
+        : 'Gather customer-supplied site, audience, source and asset context before drafting.',
+      ['Site and audience context', 'Source and claims rules'], ['A bounded content brief with verified source requirements and an existing content owner']));
+    steps.push(step('prepare-cited-content', 'customer_agent',
+      'Use the site’s content router when present, then source-cited-content-builder, source-cited-humanizer, content-defingerprinting, internal-linking-optimizer, applicable image workflow and pre-publish-review. An authored result has no AgentLinkOps account prerequisite.',
+      ['Approved task scope', 'Applicable content skills and primary-source evidence'], ['Cited content artifact and recorded review gates; draft, reviewed and published states remain distinct']));
+  } else {
+    steps.push(step('qualify-campaign-inputs', 'customer_agent',
+      'Inspect customer-selected records and assets; qualify exact source pages and claim-specific evidence. Preserve unknowns and duplicate references. An optional SQLite CRM is not required.',
+      ['Customer-selected records', 'A relevant asset and campaign objective'], ['Qualified opportunities with exact source pages, evidence, duplicate accounting and unresolved claims']));
+    steps.push(step('prepare-campaign-handoff', 'customer_agent',
+      'Prepare an external-tool draft and reviewed mapping. Keep the customer’s CRM or sender responsible for contacts, suppression, reply stops and delivery; apply required content gates to authored copy.',
+      ['Qualified opportunities', 'Chosen external tool and its supported fields'], ['Draft handoff with campaign references and supported external IDs; no sending or connection is implied']));
+  }
+  steps.push(step('record-resume-checkpoint', 'customer_agent',
+    'Prepare a checkpoint in the customer’s chosen record format for later approval to save. Preserve references, external IDs and completed evidence; read back before replaying an external action.',
+    ['Chosen record ownership and format'], ['Resumable next action; draft, sent, replied and independently verified placement states remain separate']));
+  return steps;
+}
+
+export async function setupPlanMain(argv, { cwd = process.cwd(), out = console.log } = {}) {
+  // Validate option names before the shared parser, including prototype-like keys.
+  const seen = new Set();
+  for (const value of argv) {
+    if (typeof value !== 'string') throw new ConfigError(USAGE);
+    if (!value.startsWith('--')) continue;
+    const name = value.slice(2).split('=')[0];
+    if (!['plan', 'goal', 'mode'].includes(name) || seen.has(name)) throw new ConfigError(USAGE);
+    seen.add(name);
+  }
+  const args = parseArgs(argv);
+  if (args._.length !== 1 || args._[0] !== 'setup' || args.plan !== true || !GOALS.has(args.goal)
+    || (args.mode !== undefined && !MODES.has(args.mode))) throw new ConfigError(USAGE);
+  const mode = args.mode ?? 'local';
+  const inspection = mode === 'hosted'
+    ? { status: 'skipped', reason: 'Hosted planning does not inspect or require a workspace.' }
+    : await inspectWorkspace(cwd);
+  const warnings = [];
+  let unsafe = false;
+  if (mode !== 'hosted') {
+    unsafe = inspection.workspace.status !== 'directory';
+    if (unsafe) warnings.push({ code: 'WORKSPACE_INSPECTION_INCOMPLETE', message: 'The selected workspace could not be inspected as a safe directory; no contents were read.' });
+    for (const entry of inspection.paths) {
+      const expected = PATHS.find(([path]) => path === entry.path)[1];
+      if (UNSAFE.has(entry.status) || (entry.status !== 'missing' && !expected.includes(entry.status))) {
+        unsafe = true;
+        warnings.push({ code: UNSAFE.has(entry.status) ? 'UNSAFE_OR_UNREADABLE_PATH' : 'UNEXPECTED_PATH_TYPE', path: entry.path, message: 'Resolve this known-path finding before selecting records or writing there.' });
+      }
+    }
+    warnings.push({ code: 'CUSTOM_PATHS_UNRESOLVED', message: 'Config contents and custom ledger paths were not read; absence at a standard path does not establish that no setup exists.' });
+  }
+  const plan = {
+    schemaVersion: 1,
+    kind: 'setup_plan',
+    goal: args.goal,
+    mode,
+    readOnly: true,
+    inspection,
+    capabilities: { localCli: 'available', cloudConnection: 'unverified', vendorConnections: 'unverified' },
+    steps: taskSteps(args.goal, mode, inspection, unsafe),
+    warnings,
+    effects: { filesWritten: 0, networkRequests: 0, accountsConnected: 0, messagesSent: 0 },
+  };
+  out(JSON.stringify(plan, null, 2));
+  return 0;
+}

package/cli/skill.js

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// DP-0037-T02: `agentlinkops skill` prints the agent reference, the one text an agent reads once
+// per session before its first AgentLinkOps call. The text ships inside the connect skill of the
+// pack beside this CLI (references/agentlinkops.md, generated from site/SKILL.md), so what the
+// agent reads is the version it has installed, not whatever the website serves today. A
+// checkout without a built pack falls back to site/SKILL.md itself. The nudge goes where a
+// person reads (stdout after init, stderr after a terminal `tools`, the setup report's next
+// steps); a machine reader of `tools --json` or of stderr error objects never sees it.
+export const REFERENCE_URL = 'https://agentlinkops.com/SKILL.md';
+export const NUDGE = `Run \`agentlinkops skill\` and read it in full before the first AgentLinkOps call in a session (also at ${REFERENCE_URL}).`;
+const USAGE = 'skill [--url]';
+
+export async function readReference({ from = fileURLToPath(import.meta.url), packDir = null } = {}) {
+  // The pack beside the CLI (the published package), then this repository's generated copy,
+  // then a built plugin; a stale dist/ must not shadow the generated source in a checkout.
+  const base = dirname(from);
+  const packs = packDir ? [packDir] : [join(base, '..', 'skills'), join(base, '..', 'toolkit', 'plugin', 'agentlinkops', 'skills'), join(base, '..', 'dist', 'plugin', 'agentlinkops', 'skills')];
+  for (const pack of packs) {
+    const path = join(pack, 'agentlinkops-connect', 'references', 'agentlinkops.md');
+    const text = await readFile(path, 'utf8').catch(() => null);
+    if (text) return { text, source: path };
+  }
+  const site = resolve(dirname(from), '..', 'site', 'SKILL.md');
+  const text = await readFile(site, 'utf8').catch(() => null);
+  if (text) return { text: text.replace(/^---\n[\s\S]*?\n---\n\n?/u, ''), source: site };
+  throw new Error(`No agent reference found beside this CLI; read ${REFERENCE_URL}.`);
+}
+
+export async function skillMain(argv, { out = console.log, from, packDir = null } = {}) {
+  const rest = argv.slice(1);
+  if (rest.some(a => !['--url'].includes(a))) { out(USAGE); return 2; }
+  if (rest.includes('--url')) { out(REFERENCE_URL); return 0; }
+  const { text } = await readReference({ from, packDir });
+  out(text.replace(/^<!--[^\n]*-->\n/u, '').trimEnd());
+  return 0;
+}

package/cli/state.js

@@ -0,0 +1,106 @@
+// `state.json`: when each entry was last checked, and where the cloud cursors are.
+//
+// This file exists because of a number measured by running the tool: one observation row is
+// about 2 KB, so appending every check for a thousand links daily is roughly 700 MB of git
+// churn a year, nearly all of it rows saying the same thing as the row above.
+//
+// So **the mirror records CHANGES and this file records ACTIVITY.** A repeat observation of the
+// same state with the same link signature tells a reader nothing they cannot already see, and
+// writing it only to compact it away later is doing the work twice. What would be lost — "when
+// was this last confirmed" — is exactly what a small, rewritten map answers better.
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+export const STATE_VERSION = 2;
+
+/**
+ * Brings a state file forward without losing anything it already held.
+ *
+ * Two rules, and the second is the one that matters. **Every unknown key is preserved**, because
+ * this file is written into the customer's repository and a newer version of the tool may have
+ * put something there that an older one is about to write back. And **an upgrade never invents a
+ * cursor**: a v1 file recorded one `events` cursor and knew nothing about target events, so the
+ * target cursor upgrades to `null` — start of feed — rather than being seeded from the source
+ * cursor. Seeding it would skip every target event ever emitted, and the feed would look quiet.
+ */
+export function upgradeState(raw) {
+  const state = { ...(raw ?? {}) };
+  const version = Number.isInteger(state.v) ? state.v : 1;
+  const cursors = { ...(state.cursors ?? {}) };
+  if (!('events' in cursors)) cursors.events = null;
+  if (!('target_events' in cursors)) cursors.target_events = null;
+  return {
+    ...state,
+    v: STATE_VERSION,
+    entries: state.entries ?? {},
+    cursors,
+    gaps: state.gaps ?? [],
+    // Kept so a reader can tell an upgraded file from one written at this version.
+    upgraded_from: version < STATE_VERSION ? version : (state.upgraded_from ?? null),
+  };
+}
+
+export async function readState(path) {
+  try { return upgradeState(JSON.parse(await readFile(path, 'utf8'))); }
+  catch (error) {
+    if (error.code === 'ENOENT') return upgradeState({ v: STATE_VERSION, entries: {}, cursors: {} });
+    throw error;
+  }
+}
+
+export async function writeState(path, state) {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = join(dirname(path), `.${crypto.randomUUID()}.state.tmp`);
+  // Sorted keys so a run that changes one entry produces a one-line diff.
+  const entries = Object.fromEntries(Object.entries(state.entries ?? {}).sort(([a], [b]) => (a < b ? -1 : 1)));
+  await writeFile(temporary, `${JSON.stringify({ ...state, entries }, null, 1)}\n`, 'utf8');
+  await rename(temporary, path);
+}
+
+/** When each entry was last checked, whatever the answer was. */
+export function lastCheckedMap(state) {
+  return new Map(Object.entries(state.entries ?? {}).map(([id, record]) => [id, record.last_checked]));
+}
+
+/**
+ * Splits a run's rows into the ones worth recording and the ones that repeat.
+ *
+ * A row is worth recording when it is the first for its entry, or when the state, the reason or
+ * the link signature moved. The signature is in there deliberately: a link that is still present
+ * but whose anchor or rel changed is a real event, and comparing only the state would miss it.
+ */
+export function selectChanged(rows, state) {
+  const changed = [], repeated = [];
+  for (const row of rows) {
+    const previous = state.entries?.[row.id];
+    const signature = row.result?.linkSignature ?? null;
+    const same = previous
+      && previous.last_state === row.state
+      && (previous.last_reason ?? null) === (row.reason ?? null)
+      && (previous.last_signature ?? null) === signature;
+    (same ? repeated : changed).push(row);
+  }
+  return { changed, repeated };
+}
+
+/** Applies a run to the activity record. Every check counts, recorded or not. */
+export function applyRun(state, rows) {
+  const entries = { ...(state.entries ?? {}) };
+  for (const row of rows) {
+    const previous = entries[row.id] ?? { checks: 0 };
+    entries[row.id] = {
+      ...previous,
+      last_checked: row.checked_at,
+      last_complete: row.complete === true,
+      last_placement: row.result?.sourceUrl && row.result?.targetUrl ? JSON.stringify([row.result.sourceUrl, row.result.targetUrl, row.result.targetScope ?? 'exact']) : null,
+      last_state: row.state,
+      last_reason: row.reason ?? null,
+      last_signature: row.result?.linkSignature ?? null,
+      checks: (previous.checks ?? 0) + 1,
+      // The date a placement was first seen is worth keeping where nothing can compact it away.
+      first_present: previous.first_present ?? (row.state === 'present' ? row.checked_at : null),
+      first_present_placement: previous.first_present ? previous.first_present_placement ?? null : row.state === 'present' && row.result?.sourceUrl && row.result?.targetUrl ? JSON.stringify([row.result.sourceUrl, row.result.targetUrl, row.result.targetScope ?? 'exact']) : null,
+    };
+  }
+  return { ...state, v: STATE_VERSION, entries };
+}

package/cli/status.js

@@ -0,0 +1,51 @@
+// `agentlinkops status` and `agentlinkops diff`: where intent and fact disagree, and what changed.
+//
+// This is the command the direction's selling moment actually runs. The customer commits an
+// expectation, closes the laptop, and three weeks later an agent opens the repository and reads
+// this. So it answers in the order a person cares about, not the order the data is stored in:
+// what appeared, what was lost, what we cannot say, and what needs a decision.
+import { latestByEntry } from './mirror.js';
+
+/** A ledger entry whose observations disagree with its declared intent. */
+export function disagreements(entries, observations) {
+  const latest = latestByEntry(observations);
+  const out = [];
+  for (const entry of entries) {
+    const row = latest.get(entry.id);
+    if (!row) { out.push({ entry, kind: 'never_checked' }); continue; }
+    if (entry.intent === 'expected' && ['absent','confirmed_missing'].includes(row.state) && row.complete) out.push({ entry, row, kind: 'lost' });
+    // Nothing is promoted automatically: whether a link that appeared is one we now EXPECT is
+    // a judgement about a relationship, not about HTML. So this proposes the edit and stops.
+    if (entry.intent === 'wanted' && row.state === 'present') out.push({ entry, row, kind: 'appeared', suggest: { intent: 'expected' } });
+    if (entry.intent === 'expected' && row.state === 'unknown') out.push({ entry, row, kind: 'cannot_say' });
+  }
+  return out;
+}
+
+/** Observation rows added since a marker, newest first. */
+export function since(observations, marker) {
+  if (!marker) return [...observations].reverse();
+  return observations.filter(row => String(row.checked_at) > String(marker)).reverse();
+}
+
+/** A state change for one entry, which is the only kind of row worth printing in a diff. */
+export function transitions(observations) {
+  const byEntry = new Map();
+  for (const row of observations) {
+    if (!byEntry.has(row.id)) byEntry.set(row.id, []);
+    byEntry.get(row.id).push(row);
+  }
+  const out = [];
+  for (const [id, rows] of byEntry) {
+    const ordered = [...rows].sort((a, b) => (a.checked_at < b.checked_at ? -1 : 1));
+    let previous = null;
+    for (const row of ordered) {
+      // An `unknown` is not a transition. Treating it as one would publish "your link was lost"
+      // every time a publisher's CDN had a bad afternoon.
+      if (row.state === 'unknown') continue;
+      if (previous && previous !== row.state) out.push({ id, from: previous, to: row.state, at: row.checked_at, row });
+      previous = row.state;
+    }
+  }
+  return out.sort((a, b) => (a.at < b.at ? 1 : -1));
+}

package/cli/sync.js

@@ -0,0 +1,179 @@
+import {observationFromSnapshot,eventSnapshot} from '../shared/observation-event.js';
+// `agentlinkops sync`: expectations up, events and evidence references down.
+//
+// The cloud is a mirror and a history of the customer's file, never the system of record for
+// their workflow. So sync is deliberately asymmetric: **it pushes intent and pulls facts, and it
+// never writes to the ledger.** A cloud that could rewrite `links.jsonl` would be a dashboard
+// that had learned to commit, which is the product this one exists not to be.
+import { toWatchInput, ledgerIdOf } from './ledger.js';
+import { observationRow } from './mirror.js';
+import { CloudError } from './client.js';
+
+const PUSH_BATCH = 100;
+
+export function syncPlan(entries, state, { includeWanted = false, ledgerIds = null } = {}) {
+  if (ledgerIds !== null && (!Array.isArray(ledgerIds) || ledgerIds.some(id => typeof id !== 'string') || ledgerIds.some(id => !entries.some(entry => entry.id === id))))
+    throw new CloudError('INVALID_SYNC_SELECTION', 0);
+  const selected = ledgerIds === null ? null : new Set(ledgerIds);
+  return entries.map(entry => ({ id: entry.id, intent: entry.intent,
+    action: selected && !selected.has(entry.id) ? 'stay_local'
+      : entry.intent === 'retired' ? (state.watches?.[entry.id] ? 'pause' : 'stay_local')
+      : entry.intent === 'wanted' && !includeWanted ? 'stay_local' : 'monitor',
+    watch_id: state.watches?.[entry.id] ?? null }));
+}
+
+/**
+ * Pushes every entry the cloud should be watching.
+ *
+ * Idempotent by construction rather than by bookkeeping: the cloud deduplicates a watch on
+ * (source, target, scope) and returns `created: false` for one it already has, so pushing the
+ * same ledger twice creates nothing and the second run is a no-op a customer can run freely.
+ */
+export async function pushExpectations(client, entries, state, { projectId, onProgress = null, includeWanted = false, ledgerIds = null } = {}) {
+  const plan = syncPlan(entries, state, { includeWanted, ledgerIds });
+  const actions = new Map(plan.map(row => [row.id, row.action]));
+  const watched = entries.filter(entry => actions.get(entry.id) === 'monitor');
+  const created = [], failed = [], mapping = { ...(state.watches ?? {}) };
+  for (let index = 0; index < watched.length; index += PUSH_BATCH) {
+    const batch = watched.slice(index, index + PUSH_BATCH);
+    const result = await client.importWatches(projectId, batch.map(toWatchInput));
+    for (const row of result.rows ?? []) {
+      const entry = batch[row.index];
+      if (!entry) continue;
+      if (row.error) { failed.push({ id: entry.id, code: row.error.code, message: row.error.message }); continue; }
+      mapping[entry.id] = row.watch.id;
+      if (row.watch.created !== false) created.push(entry.id);
+    }
+    onProgress?.(Math.min(index + PUSH_BATCH, watched.length), watched.length);
+  }
+  // A retired entry is PAUSED, never deleted. Its observations are the customer's history and
+  // deleting the watch would take them with it.
+  const retired = [];
+  for (const entry of entries.filter(item => actions.get(item.id) === 'pause')) {
+    const watchId = mapping[entry.id];
+    if (!watchId) continue;
+    try { await client.updateWatch(watchId, { status: 'paused' }); retired.push(entry.id); }
+    catch (error) { failed.push({ id: entry.id, code: error.code, message: error.message }); }
+  }
+  return { pushed: watched.length, created: created.length, retired: retired.length, failed, watches: mapping, local: plan.filter(row => row.action === 'stay_local').length };
+}
+
+/**
+ * Pulls the event feed into the local mirror.
+ *
+ * Two rules, both inherited from the cloud's own contract rather than invented here.
+ *
+ * **A whole page applies before the cursor advances.** A crash mid-page re-fetches that page; it
+ * never skips it.
+ *
+ * **An expired cursor resyncs, it does not skip.** The cloud answers a cursor below its floor
+ * with 410 carrying `resync_required`, a snapshot endpoint and a resume cursor. Advancing to the
+ * resume cursor WITHOUT taking the snapshot would silently drop every change in the gap, which
+ * is the exact failure the 410 exists to prevent.
+ */
+export async function pullEvents(client, state, options = {}) {
+  return pullFeed({ list: query => client.listEvents(query), exportSnapshot: query => client.exportWatches(query) }, 'events', state, options);
+}
+
+/**
+ * Pulls the TARGET event feed, on its own cursor.
+ *
+ * The cloud keeps `events` and `target_events` in separate per-workspace sequences, so a single
+ * cursor cannot address both: sequence 41 means one thing in one feed and something unrelated in
+ * the other. Sharing one would have advanced the target cursor past unread source events on every
+ * sync, and the loss would have been invisible — the feed would simply look quiet.
+ *
+ * The independence is total, and that is the part worth testing: an expiry on one feed resyncs
+ * that feed and **must not touch the other's cursor**, because the two have no reason to have
+ * expired together.
+ */
+export async function pullTargetEvents(client, state, options = {}) {
+  return pullFeed({ list: query => client.listTargetEvents(query), exportSnapshot: client.listTargets ? query => client.listTargets(query) : null }, 'target_events', state, options);
+}
+
+/** The shared walk. One cursor key per feed, and the key is the only thing that differs. */
+async function pullFeed(feed, cursorKey, state, { maxPages = 100, onSnapshot = null } = {}) {
+  const events = [], gaps = [];
+  let cursor = state.cursors?.[cursorKey] ?? null;
+  let pages = 0, resynced = false;
+  while (pages < maxPages) {
+    let page;
+    try { page = await feed.list({ cursor, limit: 100 }); }
+    catch (error) {
+      if (!(error instanceof CloudError) || error.code !== 'CURSOR_EXPIRED') throw error;
+      const details = error.details ?? {};
+      // The snapshot is taken FIRST. Only then does the cursor move, and the gap is recorded so
+      // a reader can see that something happened here rather than inferring quiet.
+      if (!feed.exportSnapshot) throw new CloudError('RESYNC_SNAPSHOT_UNAVAILABLE', 410, details);
+      if (resynced) throw new CloudError('RESYNC_REPEATED_EXPIRY', 410, details);
+      let snapshot = null, snapshotCursor = null;
+      const seen = new Set();
+      do {
+        const part = await feed.exportSnapshot({cursor: snapshotCursor, limit: 100});
+        snapshot = snapshot ? {...snapshot, items: [...snapshot.items, ...(part.items ?? [])]} : {...part, items: part.items ?? []};
+        snapshotCursor = part.next_cursor ?? null;
+        if (snapshotCursor && seen.has(snapshotCursor)) throw new CloudError('INVALID_SNAPSHOT_CURSOR', 502);
+        seen.add(snapshotCursor);
+      } while (snapshotCursor);
+      snapshot.next_cursor = null;
+      // The server's expiry watermark precedes this scan. Replaying from it catches concurrent changes.
+      for (const watch of snapshot.items) {
+        const state = watch.observation_state;
+        const at = state?.checked_at ?? state?.latestAttempt?.checkedAt;
+        if (!at) continue;
+        const after = cursorKey === 'events' ? eventSnapshot({...state, source_url:watch.source_url,target_url:watch.target_url,target_scope:watch.target_scope})
+          : {target_id:watch.id,url:watch.url,state:state.state,uncertain:state.uncertain,checked_at:at,http_status:state.latestAttempt?.httpStatus,reason:state.latestAttempt?.reason,final_url:state.latestAttempt?.finalUrl};
+        events.push({id: `snapshot:${cursorKey}:${watch.id}:${at}`, ...(cursorKey === 'events' ? {watch_id: watch.id} : {target_id: watch.id}),
+          data: {after}});
+      }
+      await onSnapshot?.(snapshot, cursorKey);
+      gaps.push({ at: new Date().toISOString(), reason: 'cursor_expired', resumed_from: details.resume_cursor ?? null });
+      cursor = details.resume_cursor ?? null;
+      resynced = true;
+      if (!details.resume_cursor) break;
+      continue;
+    }
+    events.push(...(page.events ?? []));
+    pages++;
+    // Applied, then advanced.
+    cursor = page.next_cursor ?? cursor;
+    if (!page.has_more) break;
+  }
+  // Named by feed, so a caller writing this back cannot put it under the wrong key.
+  return { feed: cursorKey, events, cursor, pages, gaps, resynced };
+}
+
+/** Cloud observations, tagged so a row never loses which machine looked. */
+export function cloudObservationRows(events, watchToLedger) {
+  const rows = [];
+  for (const event of events) {
+    const ledgerId = watchToLedger.get(event.watch_id);
+    if (!ledgerId) continue;
+    const observation = event.data?.after;
+    if (!observation?.checked_at) continue;
+    rows.push({...observationRow(ledgerId, observationFromSnapshot(observation), { source: 'cloud', evidenceKey: event.data?.evidence_key ?? null }), projection_version: 1});
+  }
+  return rows;
+}
+
+/** Ledger id per cloud watch id, from what push recorded and what the cloud reports. */
+export async function watchIndex(client, state) {
+  const index = new Map();
+  for (const [ledgerId, watchId] of Object.entries(state.watches ?? {})) index.set(watchId, ledgerId);
+  // A watch created somewhere else still carries its ledger id in `localReference`, so the
+  // mapping does not depend on this machine having been the one that pushed it.
+  // The list endpoint signals more pages with a non-null `next_cursor` and does NOT return a
+  // `has_more` flag — reading one would have silently indexed only the first hundred watches,
+  // and every event past them would have been skipped as belonging to an unknown watch.
+  let cursor = null;
+  for (let page = 0; page < 200; page++) {
+    const result = await client.listWatches({ cursor, limit: 100 });
+    for (const watch of result.items ?? []) {
+      const ledgerId = ledgerIdOf(watch.local_reference);
+      if (ledgerId) index.set(watch.id, ledgerId);
+    }
+    if (!result.next_cursor) return index;
+    cursor = result.next_cursor;
+  }
+  throw new CloudError('WATCH_INDEX_LIMIT', 502);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "agentlinkops",
+  "version": "0.5.0",
+  "description": "A backlink ledger that lives in your repository: local link checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
+  "author": "AgentLinkOps (https://agentlinkops.com)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "agentlinkops": "bin/agentlinkops.mjs",
+    "linktrail": "bin/linktrail.mjs"
+  },
+  "files": [
+    "bin",
+    "cli",
+    "src",
+    "shared",
+    "skills",
+    "templates",
+    "references",
+    "scripts",
+    ".claude-plugin",
+    ".codex-plugin",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "!**/__pycache__/",
+    "!**/*.pyc"
+  ],
+  "scripts": {
+    "test": "node --test --test-concurrency=4 test/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sunlover7/agentlinkops-cli.git"
+  },
+  "homepage": "https://agentlinkops.com/",
+  "bugs": {
+    "url": "https://github.com/sunlover7/agentlinkops-cli/issues"
+  },
+  "keywords": [
+    "mcp",
+    "backlinks",
+    "seo",
+    "agent",
+    "cli",
+    "link-monitoring",
+    "ledger",
+    "jsonl"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "parse5": "8.0.1",
+    "zod": "4.6.0"
+  }
+}