skillwiki 0.8.10-beta.3 → 0.8.10-beta.4

package/dist/cli.js

@@ -14,7 +14,7 @@ import {
 } from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
-import { join as join46 } from "path";
+import { join as join47 } from "path";
 import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
@@ -68,7 +68,8 @@ var ExitCode = {
   USAGE: 46,
   BODY_TRUNCATION_GUARD: 47,
   SYNC_LOCK_HELD: 48,
-  LOG_APPEND_LOCK_HELD: 49
+  LOG_APPEND_LOCK_HELD: 49,
+  FLEET_MANIFEST_INVALID: 50
 };
 
 // ../shared/src/json-output.ts
@@ -178,6 +179,57 @@ var MetaSchema = z.object({
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "required when provenance != research" });
   }
 });
+var hostId = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, "must be a lowercase host id");
+var endpointName = z.string().min(1).regex(/^[A-Za-z0-9_.-]+$/, "must be a hostname-like token");
+var ipAddress = z.string().min(1).regex(/^[0-9a-fA-F:.]+$/, "must be an IP address token");
+var sshAlias = z.string().min(1).regex(/^[A-Za-z0-9_.@-]+$/, "must be an SSH alias token");
+var sshUser = z.string().min(1).regex(/^[A-Za-z0-9_.-]+$/, "must be an SSH user token");
+var FleetAccessProfileSchema = z.object({
+  status: z.enum(["local", "configured", "planned", "absent", "unknown"]),
+  ssh_aliases: z.array(sshAlias).optional(),
+  users: z.array(sshUser).optional(),
+  transports: z.array(z.enum(["local", "public-ip", "tailscale", "private-lan"])).min(1)
+}).strict();
+var FleetHostIdentitySchema = z.object({
+  hostnames: z.array(endpointName).min(1),
+  public_addresses: z.array(ipAddress).optional(),
+  private_addresses: z.array(ipAddress).optional(),
+  tailscale: z.object({
+    node_names: z.array(endpointName).optional(),
+    magicdns_names: z.array(endpointName).optional(),
+    addresses: z.array(ipAddress).optional()
+  }).strict().optional()
+}).strict();
+var FleetHostSchema = z.object({
+  class: z.enum(["dev-macos", "dev-linux", "prod-linux", "unknown"]),
+  role: z.enum(["leaf", "snapshotter"]),
+  writes_to: z.array(z.enum(["s3", "github"])).min(1),
+  protected: z.boolean().optional(),
+  identity: FleetHostIdentitySchema,
+  access: z.object({
+    from: z.record(hostId, FleetAccessProfileSchema).optional()
+  }).strict().optional()
+}).strict();
+var FleetManifestSchema = z.object({
+  "$schema": z.string().url().optional(),
+  schema_version: z.literal(1),
+  vault_remote: z.string().min(1),
+  s3_remote: z.string().min(1).optional(),
+  hosts: z.record(hostId, FleetHostSchema)
+}).strict().superRefine((v, ctx) => {
+  const entries = Object.entries(v.hosts);
+  if (entries.length === 0) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["hosts"], message: "must contain at least one host" });
+  }
+  const snapshotters = entries.filter(([, host]) => host.role === "snapshotter").map(([id]) => id);
+  if (snapshotters.length !== 1) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["hosts"],
+      message: `must contain exactly one snapshotter host, found ${snapshotters.length}`
+    });
+  }
+});
 function detectSchema(fm) {
   const COMPOUND_TYPES = /* @__PURE__ */ new Set(["lesson", "pattern", "antipattern", "gotcha"]);
   if (typeof fm.type === "string" && COMPOUND_TYPES.has(fm.type) && "project" in fm) return { schema: "compound" };
@@ -793,6 +845,7 @@ import { dirname as dirname2 } from "path";
 var CONFIG_KEYS = [
   "WIKI_PATH",
   "WIKI_LANG",
+  "SKILLWIKI_HOST_ID",
   "AUTO_COMMIT",
   "BACKUP_ENDPOINT",
   "BACKUP_BUCKET",
@@ -3075,6 +3128,7 @@ function buildCliSurface() {
   program2.command("observe").requiredOption("--text <text>").option("--kind <kind>").option("--project <slug>").option("--wiki <name>");
   program2.command("session-brief").option("--project <slug>").option("--write").option("--wiki <name>");
   program2.command("ingest").requiredOption("--vault <path>").requiredOption("--type <type>").requiredOption("--title <title>").option("--tags <csv>").option("--provenance <provenance>").option("--dry-run");
+  program2.command("fleet");
   const graphCmd = program2.commands.find((c) => c.name() === "graph");
   graphCmd.command("build").option("--out <path>").option("--wiki <name>");
   const canvasCmd2 = program2.commands.find((c) => c.name() === "canvas");
@@ -3098,6 +3152,9 @@ function buildCliSurface() {
   const backupCmd2 = program2.commands.find((c) => c.name() === "backup");
   backupCmd2.command("sync").option("--dry-run").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--prune").option("--wiki <name>");
   backupCmd2.command("restore").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--target <dir>").option("--wiki <name>");
+  const fleetCmd2 = program2.commands.find((c) => c.name() === "fleet");
+  fleetCmd2.command("validate");
+  fleetCmd2.command("context").option("--file <path>").option("--host-id <id>");
   const surface = /* @__PURE__ */ new Map();
   const rootFlags = new Set(program2.options.map((o) => o.long ?? o.short).filter((f) => f != null));
   function walk2(cmd, prefix, parentFlags) {
@@ -9406,15 +9463,245 @@ async function loadOrBuildGraph(vault) {
   }
 }
 
+// src/commands/fleet.ts
+import { readFile as readFile29 } from "fs/promises";
+import { hostname as nodeHostname, userInfo } from "os";
+import { join as join45 } from "path";
+import yaml3 from "js-yaml";
+var FLEET_REL_PATH = join45("projects", "llm-wiki", "architecture", "fleet.yaml");
+async function runFleetValidate(input) {
+  const loaded = await loadFleetManifest(input.file);
+  if (!loaded.ok) {
+    if (loaded.error === "FILE_NOT_FOUND") {
+      return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: input.file }) };
+    }
+    const errors = fleetLoadErrors(loaded);
+    return invalidFleet(errors);
+  }
+  const warnings = fleetWarnings(loaded.manifest);
+  const snapshotter = findSnapshotter(loaded.manifest);
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      valid: true,
+      errors: [],
+      warnings,
+      host_count: Object.keys(loaded.manifest.hosts).length,
+      snapshotter,
+      humanHint: `VALID fleet manifest (${Object.keys(loaded.manifest.hosts).length} hosts; snapshotter: ${snapshotter ?? "none"})`
+    })
+  };
+}
+async function runFleetContext(input) {
+  const env = input.env ?? process.env;
+  const home = input.home ?? env.HOME ?? "";
+  const cwd = input.cwd ?? process.cwd();
+  const osHostname = input.osHostname ?? safeEnvValue(env.HOSTNAME) ?? nodeHostname();
+  const user = input.user ?? safeEnvValue(env.USER) ?? safeUserName();
+  const vault = input.vault ?? safeEnvValue(env.WIKI_PATH);
+  const file = input.file ?? (vault ? join45(vault, FLEET_REL_PATH) : void 0);
+  const loaded = file ? await loadFleetManifest(file) : { ok: false, error: "FILE_NOT_FOUND" };
+  if (!loaded.ok) {
+    const markdown2 = formatUnknownContext({ osHostname, user, cwd, vault, reason: "fleet manifest unavailable or invalid" });
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({ manifest_loaded: false, markdown: markdown2, humanHint: markdown2 })
+    };
+  }
+  const resolved = await resolveHostId({
+    manifest: loaded.manifest,
+    hostId: input.hostId,
+    env,
+    home,
+    osHostname
+  });
+  if (!resolved.hostId || !loaded.manifest.hosts[resolved.hostId]) {
+    const markdown2 = formatUnknownContext({ osHostname, user, cwd, vault, reason: "host identity is unresolved" });
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({ manifest_loaded: true, markdown: markdown2, humanHint: markdown2 })
+    };
+  }
+  const markdown = formatKnownContext({
+    manifest: loaded.manifest,
+    hostId: resolved.hostId,
+    source: resolved.source,
+    osHostname,
+    user,
+    cwd,
+    vault
+  });
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      manifest_loaded: true,
+      host_id: resolved.hostId,
+      source: resolved.source,
+      markdown,
+      humanHint: markdown
+    })
+  };
+}
+async function loadFleetManifest(file) {
+  let text;
+  try {
+    text = await readFile29(file, "utf8");
+  } catch {
+    return { ok: false, error: "FILE_NOT_FOUND" };
+  }
+  let parsed;
+  try {
+    parsed = yaml3.load(text, { schema: yaml3.JSON_SCHEMA });
+  } catch (error) {
+    return { ok: false, error: "INVALID_YAML", detail: error instanceof Error ? error.message : String(error) };
+  }
+  const result = FleetManifestSchema.safeParse(parsed);
+  if (!result.success) {
+    return { ok: false, error: "INVALID_FLEET_MANIFEST", detail: result.error.issues };
+  }
+  return { ok: true, manifest: result.data };
+}
+function invalidFleet(errors) {
+  return {
+    exitCode: ExitCode.FLEET_MANIFEST_INVALID,
+    result: ok({
+      valid: false,
+      errors,
+      warnings: [],
+      host_count: 0,
+      humanHint: `INVALID fleet manifest
+${errors.map((e) => `  ${e.path || "(root)"}: ${e.message}`).join("\n")}`
+    })
+  };
+}
+function fleetLoadErrors(loaded) {
+  if (loaded.error === "INVALID_YAML") {
+    return [{ path: "", message: `invalid YAML: ${String(loaded.detail ?? "parse failed")}` }];
+  }
+  if (loaded.error === "INVALID_FLEET_MANIFEST" && Array.isArray(loaded.detail)) {
+    return loaded.detail.map((issue) => {
+      const zodIssue = issue;
+      return {
+        path: (zodIssue.path ?? []).join("."),
+        message: zodIssue.message ?? "invalid value"
+      };
+    });
+  }
+  return [{ path: "", message: loaded.error }];
+}
+function fleetWarnings(manifest) {
+  const warnings = [];
+  for (const [id, host] of Object.entries(manifest.hosts)) {
+    if (host.role === "snapshotter" && host.protected !== true) {
+      warnings.push(`snapshotter host '${id}' is not protected=true`);
+    }
+  }
+  return warnings;
+}
+function findSnapshotter(manifest) {
+  return Object.entries(manifest.hosts).find(([, host]) => host.role === "snapshotter")?.[0];
+}
+async function resolveHostId(input) {
+  if (input.hostId) return { hostId: input.hostId, source: "host-id" };
+  if (input.env.SKILLWIKI_HOST_ID) return { hostId: input.env.SKILLWIKI_HOST_ID, source: "SKILLWIKI_HOST_ID" };
+  if (input.env.AGENT_HOST_ID) return { hostId: input.env.AGENT_HOST_ID, source: "AGENT_HOST_ID" };
+  if (input.home) {
+    const dotenv = await parseDotenvFile(join45(input.home, ".skillwiki", ".env"));
+    if (dotenv.SKILLWIKI_HOST_ID) {
+      return { hostId: dotenv.SKILLWIKI_HOST_ID, source: "~/.skillwiki/.env:SKILLWIKI_HOST_ID" };
+    }
+  }
+  if (input.env.VS_HOSTNAME) return { hostId: input.env.VS_HOSTNAME, source: "VS_HOSTNAME" };
+  const hostname = input.osHostname.trim();
+  if (hostname) {
+    if (input.manifest.hosts[hostname]) return { hostId: hostname, source: "hostname" };
+    const byHostname = Object.entries(input.manifest.hosts).find(([, host]) => host.identity.hostnames.includes(hostname));
+    if (byHostname) return { hostId: byHostname[0], source: "hostname" };
+  }
+  return {};
+}
+function formatKnownContext(input) {
+  const host = input.manifest.hosts[input.hostId];
+  const protectedValue = host.protected === true ? "true" : "false";
+  const writesTo = host.writes_to.join(", ");
+  const selfAliases = collectSelfAliases(input.manifest, input.hostId);
+  const outbound = collectOutboundHosts(input.manifest, input.hostId);
+  const guidance = input.hostId === "macos-dev" ? "use declared SSH aliases for remote work when needed; do not assume undeclared hosts have reciprocal SSH access." : `this session is already on \`${input.hostId}\`; do not SSH to self aliases unless the user explicitly asks. Do not assume outbound SSH to other fleet hosts is configured.`;
+  return [
+    "## Runtime Host Context",
+    "",
+    `- Current machine: \`${input.hostId}\`${input.source ? ` (source: \`${input.source}\`)` : ""}`,
+    `- OS hostname: ${formatMaybe(input.osHostname)}`,
+    `- User: ${formatMaybe(input.user)}`,
+    `- Workspace: ${formatMaybe(input.cwd)}`,
+    `- Vault: ${formatMaybe(input.vault)}`,
+    `- Fleet role: \`${host.role}\`; protected: \`${protectedValue}\`; writes_to: \`${writesTo}\``,
+    `- Self SSH aliases known in fleet: ${formatList(selfAliases)}`,
+    `- Declared outbound SSH from this source: ${outbound.length > 0 ? formatList(outbound) : "none"}`,
+    `- Guidance: ${guidance}`
+  ].join("\n");
+}
+function formatUnknownContext(input) {
+  return [
+    "## Runtime Host Context",
+    "",
+    "- Current machine: unknown",
+    `- OS hostname: ${formatMaybe(input.osHostname)}`,
+    `- User: ${formatMaybe(input.user)}`,
+    `- Workspace: ${formatMaybe(input.cwd)}`,
+    `- Vault: ${formatMaybe(input.vault)}`,
+    "- Fleet role: unknown",
+    "- Self SSH aliases known in fleet: unknown",
+    "- Declared outbound SSH from this source: unknown",
+    `- Guidance: ${input.reason}; do not assume local vs remote role. Inspect runtime or ask before SSH/deploy/sync work.`
+  ].join("\n");
+}
+function collectSelfAliases(manifest, hostId2) {
+  const aliases = [];
+  const host = manifest.hosts[hostId2];
+  const access = host?.access?.from ?? {};
+  for (const profile of Object.values(access)) {
+    for (const alias of profile.ssh_aliases ?? []) aliases.push(alias);
+  }
+  return [...new Set(aliases)];
+}
+function collectOutboundHosts(manifest, sourceHostId) {
+  const hosts = [];
+  for (const [targetId, target] of Object.entries(manifest.hosts)) {
+    if (targetId === sourceHostId) continue;
+    const profile = target.access?.from?.[sourceHostId];
+    if (profile && (profile.status === "configured" || profile.status === "local")) {
+      hosts.push(targetId);
+    }
+  }
+  return hosts.sort();
+}
+function formatList(values) {
+  return values.length > 0 ? values.map((v) => `\`${v}\``).join(", ") : "none";
+}
+function formatMaybe(value) {
+  return value && value.trim().length > 0 ? `\`${value}\`` : "unknown";
+}
+function safeEnvValue(value) {
+  return value && value.trim().length > 0 ? value : void 0;
+}
+function safeUserName() {
+  try {
+    return userInfo().username;
+  } catch {
+    return "";
+  }
+}
+
 // src/utils/auto-commit.ts
 import { existsSync as existsSync19 } from "fs";
-import { join as join45 } from "path";
+import { join as join46 } from "path";
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
   const home = process.env.HOME ?? "";
   const dotenv = await parseDotenvFile(configPath(home));
   if (dotenv["AUTO_COMMIT"] === "false") return;
-  if (!existsSync19(join45(vault, ".git"))) return;
+  if (!existsSync19(join46(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -9465,7 +9752,7 @@ program.command("validate <file>").description("validate vault page frontmatter
   emit(await runValidate({ file, apply: !!opts.apply, vault }), vault);
 });
 program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path (default: <vault>/.skillwiki/graph.json)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
-  const out = opts.out ?? join46(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join47(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -9837,6 +10124,22 @@ program.command("ingest <source>").description("ingest a source URL or local fil
     dryRun: !!opts.dryRun
   }), opts.vault);
 });
+var fleetCmd = program.command("fleet").description("manage fleet topology metadata");
+fleetCmd.command("validate <file>").description("validate a fleet manifest").action(async (file) => {
+  emit(await runFleetValidate({ file }));
+});
+fleetCmd.command("context [vault]").description("render compact Runtime Host Context for SessionStart").option("--file <path>", "fleet manifest path").option("--host-id <id>", "explicit current fleet host id").action(async (vault, opts) => {
+  emit(await runFleetContext({
+    vault,
+    file: opts.file,
+    hostId: opts.hostId,
+    env: process.env,
+    home: process.env.HOME ?? "",
+    cwd: process.cwd(),
+    osHostname: process.env.HOSTNAME,
+    user: process.env.USER
+  }));
+});
 for (const w of getDeprecatedWarnings(process.env.HOME ?? "")) {
   process.stderr.write(w + "\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.10-beta.3",
+  "version": "0.8.10-beta.4",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.10-beta.3",
+  "version": "0.8.10-beta.4",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.10-beta.3",
+  "version": "0.8.10-beta.4",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/hooks/session-context

@@ -183,6 +183,43 @@ build_dynamic_session_memory() {
     return 0
 }
 
+build_runtime_host_context() {
+    local vault
+    vault=$(resolve_vault_path_for_session)
+
+    if command -v skillwiki >/dev/null 2>&1; then
+        local context
+        if [[ -n "$vault" && -d "$vault" ]]; then
+            context=$(skillwiki --human fleet context "$vault" 2>/dev/null || true)
+        else
+            context=$(skillwiki --human fleet context 2>/dev/null || true)
+        fi
+        if [[ "$context" == *"## Runtime Host Context"* ]]; then
+            printf '%s' "$context"
+            return 0
+        fi
+    fi
+
+    local os_hostname
+    local current_user
+    os_hostname=$(hostname -s 2>/dev/null || hostname 2>/dev/null || printf '')
+    current_user=$(id -un 2>/dev/null || printf '%s' "${USER:-}")
+
+    cat <<EOF
+## Runtime Host Context
+
+- Current machine: unknown
+- OS hostname: \`${os_hostname:-unknown}\`
+- User: \`${current_user:-unknown}\`
+- Workspace: \`${PWD}\`
+- Vault: \`${vault:-unknown}\`
+- Fleet role: unknown
+- Self SSH aliases known in fleet: unknown
+- Declared outbound SSH from this source: unknown
+- Guidance: host identity is unresolved; do not assume local vs remote role. Inspect runtime or ask before SSH/deploy/sync work.
+EOF
+}
+
 escape_for_json() {
     local s="$1"
     s="${s//\\/\\\\}"
@@ -219,12 +256,18 @@ build_skillwiki_session_context() {
     local skill_content="$1"
     local project_prd_context
     local dynamic_session_memory
+    local runtime_host_context
     local session_context
 
     project_prd_context=$(build_project_prd_context)
     dynamic_session_memory=$(build_dynamic_session_memory)
+    runtime_host_context=$(build_runtime_host_context)
 
     session_context=$'### Skillwiki Activation\n\nSkillwiki is active for this workspace. Below are the capability guidelines for local reference:'
+    if [[ -n "$runtime_host_context" ]]; then
+        session_context+=$'\n\n'
+        session_context+="$runtime_host_context"
+    fi
     if [[ -n "$dynamic_session_memory" ]]; then
         session_context+=$'\n\n'
         session_context+="$dynamic_session_memory"

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.8.10-beta.3",
+  "version": "0.8.10-beta.4",
   "private": true,
   "files": [
     "wiki-*",