mdkg 0.0.8 → 0.0.9

package/dist/init/templates/default/feedback.md

@@ -0,0 +1,27 @@
+---
+id: {{id}}
+type: feedback
+title: {{title}}
+version: 0.1.0
+target_id: work.example
+sentiment: neutral
+feedback_status: new
+source_ref: user.example
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Feedback
+
+Capture high-signal feedback without raw secrets.
+
+# Evidence
+
+List supporting references and artifacts.

package/dist/init/templates/default/proposal.md

@@ -0,0 +1,35 @@
+---
+id: {{id}}
+type: proposal
+title: {{title}}
+version: 0.1.0
+target_id: work.example
+proposal_status: proposed
+proposal_kind: work_update
+evidence_refs: []
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Summary
+
+Summarize the improvement proposal.
+
+# Evidence
+
+List feedback, receipts, disputes, or other evidence.
+
+# Proposed Change
+
+Describe the proposed update to a SPEC.md, WORK.md, or SKILL.md.
+
+# Review
+
+Capture review status and next decision points.

package/dist/init/templates/default/receipt.md

@@ -0,0 +1,31 @@
+---
+id: {{id}}
+type: receipt
+title: {{title}}
+version: 0.1.0
+work_order_id: order.example
+receipt_status: recorded
+outcome: success
+cost_ref: cost.redacted
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Outcome
+
+Record the result and proof summary.
+
+# Artifacts
+
+List committed artifact references.
+
+# Notes
+
+Capture non-secret execution notes.

package/dist/init/templates/default/spec.md

@@ -0,0 +1,43 @@
+---
+id: {{id}}
+type: spec
+title: {{title}}
+version: 0.1.0
+role: subagent
+runtime_mode: room_orchestrated
+work_contracts: []
+requested_capabilities: []
+skill_refs: []
+tool_refs: []
+model_refs: []
+wasm_component_refs: []
+runtime_image_refs: []
+subagent_refs: []
+resource_profile: builder
+update_policy: manual
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Purpose
+
+Define the agent, package, or runtime specification.
+
+# Runtime
+
+Describe role, runtime mode, resource profile, and update policy.
+
+# Work Contracts
+
+List related WORK.md contracts.
+
+# Capabilities
+
+List requested capabilities and relevant constraints.

package/dist/init/templates/default/work.md

@@ -0,0 +1,44 @@
+---
+id: {{id}}
+type: work
+title: {{title}}
+version: 0.1.0
+agent_id: agent.example
+kind: generic
+pricing_model: quoted
+required_capabilities: []
+skill_refs: []
+tool_refs: []
+model_refs: []
+wasm_component_refs: []
+runtime_image_refs: []
+subagent_refs: []
+inputs: [request:text:required]
+outputs: [result:text:required]
+receipt_required: true
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Capability
+
+Describe the reusable capability contract.
+
+# Inputs
+
+Document input descriptors and validation expectations.
+
+# Outputs
+
+Document output descriptors and artifact expectations.
+
+# Receipt
+
+Describe required receipt evidence.

package/dist/init/templates/default/work_order.md

@@ -0,0 +1,32 @@
+---
+id: {{id}}
+type: work_order
+title: {{title}}
+version: 0.1.0
+work_id: work.example
+work_version: 0.1.0
+requester: user.example
+order_status: submitted
+request_ref: request.example
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+refs: []
+aliases: []
+created: {{created}}
+updated: {{updated}}
+---
+
+# Request
+
+Capture the concrete request against a WORK.md version.
+
+# Inputs
+
+Record committed input references without secrets.
+
+# Constraints
+
+Capture relevant policy, budget, and artifact constraints.

package/dist/pack/export_json.js

@@ -15,6 +15,9 @@ function buildFrontmatter(node) {
     if (node.aliases.length > 0) {
         frontmatter.aliases = node.aliases;
     }
+    for (const [key, value] of Object.entries(node.attributes ?? {})) {
+        frontmatter[key] = value;
+    }
     return frontmatter;
 }
 function exportJson(pack) {

package/dist/pack/export_md.js

@@ -7,6 +7,12 @@ function formatList(label, values) {
     }
     return `${label}: ${values.join(", ")}`;
 }
+function formatAttribute(label, value) {
+    if (Array.isArray(value)) {
+        return formatList(label, value);
+    }
+    return `${label}: ${String(value)}`;
+}
 function renderHeader(meta, nodes) {
     const lines = [];
     lines.push("# mdkg pack");
@@ -56,6 +62,9 @@ function renderNode(node) {
     if (node.refs.length > 0) {
         lines.push(formatList("refs", node.refs));
     }
+    for (const [key, value] of Object.entries(node.attributes ?? {})) {
+        lines.push(formatAttribute(key, value));
+    }
     if (node.body.trim().length > 0) {
         lines.push("");
         lines.push(node.body);

package/dist/pack/export_xml.js

@@ -21,6 +21,12 @@ function listItems(tag, itemTag, items, indent) {
     lines.push(`${indent}</${tag}>`);
     return lines;
 }
+function attributeLines(key, value, indent) {
+    if (Array.isArray(value)) {
+        return listItems(key, "item", value, indent);
+    }
+    return [`${indent}<${key}>${escapeXml(String(value))}</${key}>`];
+}
 function exportXml(pack) {
     const lines = [];
     lines.push("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
@@ -78,6 +84,9 @@ function exportXml(pack) {
         lines.push(...listItems("artifacts", "artifact", node.artifacts, "        "));
         lines.push(...listItems("refs", "ref", node.refs, "        "));
         lines.push(...listItems("aliases", "alias", node.aliases, "        "));
+        for (const [key, value] of Object.entries(node.attributes ?? {})) {
+            lines.push(...attributeLines(key, value, "        "));
+        }
         lines.push("      </frontmatter>");
         lines.push(`      <body>${escapeXml(node.body)}</body>`);
         lines.push("    </node>");

package/dist/pack/order.js

@@ -8,6 +8,13 @@ const FALLBACK_TYPES = [
     "rule",
     "prd",
     "prop",
+    "spec",
+    "work",
+    "work_order",
+    "receipt",
+    "feedback",
+    "dispute",
+    "proposal",
     "epic",
     "feat",
     "task",

package/dist/pack/pack.js

@@ -124,6 +124,7 @@ function buildPackNode(root, index, qid) {
         artifacts: node.artifacts,
         refs: node.refs,
         aliases: node.aliases,
+        attributes: node.attributes ?? {},
         body,
     };
 }

package/dist/templates/loader.js

@@ -48,8 +48,8 @@ function renderTokenValue(value) {
     }
     return value;
 }
-function renderTemplate(template, context, allowedKeysInput) {
-    const allowedKeys = new Set(allowedKeysInput ?? Object.keys(template.frontmatter));
+function renderTemplate(template, context) {
+    const allowedKeys = new Set(Object.keys(template.frontmatter));
     const rendered = {};
     for (const [key, value] of Object.entries(template.frontmatter)) {
         if (isTokenPlaceholder(value)) {

package/dist/util/argparse.js

@@ -4,6 +4,7 @@ exports.parseArgs = parseArgs;
 const NORMALIZE_VALUE_FLAGS = new Set(["--ws", "--type", "--status", "--template", "--epic"]);
 const VALUE_FLAGS = new Set([
     "--root",
+    "--id",
     "--ws",
     "--type",
     "--status",

package/dist/util/id.js

@@ -1,13 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCanonicalId = isCanonicalId;
+exports.isPortableId = isPortableId;
 exports.isCanonicalIdRef = isCanonicalIdRef;
+exports.isPortableIdRef = isPortableIdRef;
 const NUMERIC_ID_RE = /^[a-z]+-[0-9]+$/;
 const WORKSPACE_RE = /^[a-z][a-z0-9_]*$/;
+const PORTABLE_ID_RE = /^[a-z][a-z0-9_]*(?:[._-][a-z0-9_]+)*$/;
 const SPECIAL_IDS = new Set(["rule-guide", "rule-soul", "rule-human"]);
 function isCanonicalId(value) {
     return NUMERIC_ID_RE.test(value) || SPECIAL_IDS.has(value);
 }
+function isPortableId(value) {
+    return isCanonicalId(value) || PORTABLE_ID_RE.test(value);
+}
 function isCanonicalIdRef(value) {
     const normalized = value.toLowerCase();
     const parts = normalized.split(":");
@@ -21,3 +27,16 @@ function isCanonicalIdRef(value) {
     const id = parts[1] ?? "";
     return WORKSPACE_RE.test(workspace) && isCanonicalId(id);
 }
+function isPortableIdRef(value) {
+    const normalized = value.toLowerCase();
+    const parts = normalized.split(":");
+    if (parts.length === 1) {
+        return isPortableId(parts[0] ?? "");
+    }
+    if (parts.length !== 2) {
+        return false;
+    }
+    const workspace = parts[0] ?? "";
+    const id = parts[1] ?? "";
+    return WORKSPACE_RE.test(workspace) && isPortableId(id);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -12,8 +12,12 @@
     "test": "npm run build && npm run build:test && node --test dist/tests/**/*.test.js",
     "test:coverage": "npm run build && npm run build:test && node --test --experimental-test-coverage dist/tests/**/*.test.js",
     "smoke:consumer": "npm run build && node scripts/smoke-consumer.js",
+    "smoke:matrix": "npm run build && node scripts/smoke-command-matrix.js",
     "cli:snapshot": "npm run build && node scripts/cli_help_snapshot.js",
-    "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check"
+    "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
+    "prepack": "npm run build && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && node scripts/assert-publish-ready.js",
+    "postinstall": "node scripts/postinstall.js"
   },
   "devDependencies": {
     "@types/node": "^18.19.0",
@@ -28,7 +32,10 @@
     "dist/pack/",
     "dist/templates/",
     "dist/util/",
+    "scripts/postinstall.js",
     "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "LICENSE"
   ],
   "engines": {

package/scripts/postinstall.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+function readPackageVersion() {
+  try {
+    const pkgPath = path.resolve(__dirname, "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function npmCommand(platform = process.platform) {
+  return platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function npmPrefixGlobal(env = process.env, platform = process.platform, spawn = spawnSync) {
+  if (env.npm_config_prefix) {
+    return env.npm_config_prefix;
+  }
+  const result = spawn(npmCommand(platform), ["prefix", "-g"], {
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+  if (result.status !== 0) {
+    return undefined;
+  }
+  const prefix = String(result.stdout || "").trim();
+  return prefix || undefined;
+}
+
+function globalBinFromPrefix(prefix, platform = process.platform) {
+  if (!prefix) {
+    return undefined;
+  }
+  return platform === "win32" ? prefix : path.join(prefix, "bin");
+}
+
+function pathIncludesDir(dir, env = process.env, platform = process.platform) {
+  if (!dir) {
+    return false;
+  }
+  const currentPath = env.PATH || "";
+  return currentPath
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((entry) => path.resolve(entry) === path.resolve(dir));
+}
+
+function buildPostinstallMessage(env = process.env, platform = process.platform, spawn = spawnSync) {
+  const version = readPackageVersion();
+  const lines = [
+    `mdkg ${version} installed.`,
+    "",
+    "Start here:",
+    "  mdkg --help",
+  ];
+
+  const prefix = npmPrefixGlobal(env, platform, spawn);
+  const globalBin = globalBinFromPrefix(prefix, platform);
+  if (platform !== "win32" && globalBin && !pathIncludesDir(globalBin, env, platform)) {
+    lines.push(
+      "",
+      "If your shell cannot find mdkg, add npm's global bin directory to PATH:",
+      "",
+      "# zsh",
+      `echo 'export PATH="${globalBin}:$PATH"' >> ~/.zshrc`,
+      "",
+      "# bash",
+      `echo 'export PATH="${globalBin}:$PATH"' >> ~/.bashrc`
+    );
+  }
+
+  return lines.join("\n");
+}
+
+if (require.main === module) {
+  console.log(buildPostinstallMessage());
+}
+
+module.exports = {
+  buildPostinstallMessage,
+  globalBinFromPrefix,
+  pathIncludesDir,
+};