@newtype-ai/nit 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// nit — version control for agent cards
+import {
+  branch,
+  checkout,
+  commit,
+  diff,
+  formatDiff,
+  init,
+  log,
+  push,
+  remote,
+  status
+} from "./chunk-5EGCFUZ7.js";
+
+// src/cli.ts
+var bold = (s) => `\x1B[1m${s}\x1B[0m`;
+var green = (s) => `\x1B[32m${s}\x1B[0m`;
+var yellow = (s) => `\x1B[33m${s}\x1B[0m`;
+var red = (s) => `\x1B[31m${s}\x1B[0m`;
+var dim = (s) => `\x1B[2m${s}\x1B[0m`;
+async function main() {
+  const [, , command, ...args] = process.argv;
+  try {
+    switch (command) {
+      case "init":
+        await cmdInit();
+        break;
+      case "status":
+        await cmdStatus();
+        break;
+      case "commit":
+        await cmdCommit(args);
+        break;
+      case "log":
+        await cmdLog();
+        break;
+      case "diff":
+        await cmdDiff(args);
+        break;
+      case "branch":
+        await cmdBranch(args);
+        break;
+      case "checkout":
+        await cmdCheckout(args);
+        break;
+      case "push":
+        await cmdPush(args);
+        break;
+      case "remote":
+        await cmdRemote();
+        break;
+      case "help":
+      case "--help":
+      case "-h":
+      case void 0:
+        printUsage();
+        break;
+      default:
+        console.error(`nit: '${command}' is not a nit command. See 'nit help'.`);
+        process.exit(1);
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(red(`error: ${msg}`));
+    process.exit(1);
+  }
+}
+async function cmdInit() {
+  const result = await init();
+  console.log(bold("Initialized nit repository"));
+  console.log();
+  console.log(`  Public key:  ${green(result.publicKey)}`);
+  if (result.cardUrl) {
+    console.log(`  Card URL:    ${result.cardUrl}`);
+  }
+  if (result.skillsFound.length > 0) {
+    console.log(`  Skills:      ${result.skillsFound.join(", ")}`);
+  } else {
+    console.log(`  Skills:      ${dim("(none discovered)")}`);
+  }
+  console.log();
+  console.log(dim("Created .nit/ with initial commit on main."));
+}
+async function cmdStatus() {
+  const s = await status();
+  console.log(`On branch ${bold(s.branch)}`);
+  console.log(`Public key: ${dim(s.publicKey)}`);
+  console.log();
+  if (s.uncommittedChanges) {
+    console.log(yellow("Uncommitted changes:"));
+    console.log(formatDiff(s.uncommittedChanges));
+    console.log();
+  } else {
+    console.log(green("Working card clean."));
+    console.log();
+  }
+  if (s.branches.length > 0) {
+    for (const b of s.branches) {
+      const marker = b.name === s.branch ? "* " : "  ";
+      const ahead = b.ahead > 0 ? yellow(` [ahead ${b.ahead}]`) : "";
+      console.log(`${marker}${b.name}${ahead}`);
+    }
+  }
+}
+async function cmdCommit(args) {
+  let message = "";
+  const mIndex = args.indexOf("-m");
+  if (mIndex !== -1 && args[mIndex + 1]) {
+    message = args[mIndex + 1];
+  } else {
+    console.error('Usage: nit commit -m "message"');
+    process.exit(1);
+  }
+  const c = await commit(message);
+  console.log(
+    `${dim(`[${c.hash.slice(0, 8)}]`)} ${c.message}`
+  );
+}
+async function cmdLog() {
+  const commits = await log();
+  for (const c of commits) {
+    const date = new Date(c.timestamp * 1e3).toISOString().slice(0, 19);
+    console.log(
+      `${yellow(c.hash.slice(0, 8))} ${c.message} ${dim(`(${c.author}, ${date})`)}`
+    );
+  }
+  if (commits.length === 0) {
+    console.log(dim("No commits yet."));
+  }
+}
+async function cmdDiff(args) {
+  const target = args[0];
+  const d = await diff(target);
+  console.log(formatDiff(d));
+}
+async function cmdBranch(args) {
+  const name = args[0];
+  const branches = await branch(name);
+  if (name) {
+    console.log(`Branch '${green(name)}' created.`);
+  }
+  let currentBranch;
+  try {
+    const s = await status();
+    currentBranch = s.branch;
+  } catch {
+    currentBranch = "";
+  }
+  for (const b of branches) {
+    if (b.name === currentBranch) {
+      console.log(`* ${green(b.name)}`);
+    } else {
+      console.log(`  ${b.name}`);
+    }
+  }
+}
+async function cmdCheckout(args) {
+  const branchName = args[0];
+  if (!branchName) {
+    console.error("Usage: nit checkout <branch>");
+    process.exit(1);
+  }
+  await checkout(branchName);
+  console.log(`Switched to branch '${green(branchName)}'.`);
+}
+async function cmdPush(args) {
+  const all = args.includes("--all");
+  const results = await push({ all });
+  for (const r of results) {
+    if (r.success) {
+      console.log(`${green("\u2713")} ${r.branch} \u2192 ${r.remoteUrl}`);
+    } else {
+      console.log(`${red("\u2717")} ${r.branch}: ${r.error}`);
+    }
+  }
+}
+async function cmdRemote() {
+  const info = await remote();
+  console.log(`${bold(info.name)}`);
+  console.log(`  URL:        ${info.url}`);
+  console.log(
+    `  Credential: ${info.hasCredential ? green("configured") : yellow("not set")}`
+  );
+}
+function printUsage() {
+  console.log(`
+${bold("nit")} \u2014 version control for agent cards
+
+${bold("Usage:")} nit <command> [options]
+
+${bold("Commands:")}
+  init               Initialize .nit/ in current directory
+  status             Show current branch and uncommitted changes
+  commit -m "msg"    Snapshot agent-card.json
+  log                Show commit history
+  diff [target]      Compare card vs HEAD, branch, or commit
+  branch [name]      List branches or create a new one
+  checkout <branch>  Switch branch (overwrites agent-card.json)
+  push [--all]       Push branch(es) to remote
+  remote             Show remote info
+
+${bold("Examples:")}
+  nit init
+  nit branch faam.fun
+  nit checkout faam.fun
+  ${dim("# edit agent-card.json for FAAM...")}
+  nit commit -m "FAAM config"
+  nit push --all
+`.trim());
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,243 @@
+/** Commit object referencing a card snapshot. */
+interface NitCommit {
+    type: 'commit';
+    /** SHA-256 hex digest of the serialized commit */
+    hash: string;
+    /** Card object hash */
+    card: string;
+    /** Parent commit hash (null for initial commit) */
+    parent: string | null;
+    /** Author name or ID */
+    author: string;
+    /** Unix timestamp in seconds */
+    timestamp: number;
+    /** Commit message */
+    message: string;
+}
+/** A branch is a named pointer to a commit hash. */
+interface NitBranch {
+    name: string;
+    commitHash: string;
+}
+/** HEAD is always a symbolic ref pointing to a branch. */
+interface NitHead {
+    type: 'ref';
+    /** e.g. "refs/heads/main" */
+    ref: string;
+}
+/** Remote configuration for a single named remote. */
+interface NitRemoteConfig {
+    /** Push credential (Bearer token) */
+    credential?: string;
+}
+/** Full .nit/config file contents. */
+interface NitConfig {
+    /** Keyed by remote name (e.g. "origin") */
+    remotes: Record<string, NitRemoteConfig>;
+}
+/** A2A-compatible agent card. */
+interface AgentCard {
+    protocolVersion: string;
+    name: string;
+    description: string;
+    version: string;
+    url: string;
+    /** Format: "ed25519:<base64>" — present only on main branch */
+    publicKey?: string;
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    skills: AgentCardSkill[];
+    iconUrl?: string;
+    documentationUrl?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+}
+/** A single skill entry in an agent card. */
+interface AgentCardSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+/** Metadata extracted from a SKILL.md frontmatter. */
+interface SkillMetadata {
+    /** Directory name (e.g. "seo-audit") */
+    id: string;
+    /** From frontmatter `name` field */
+    name: string;
+    /** From frontmatter `description` field */
+    description: string;
+    /** From frontmatter `metadata.version` */
+    version?: string;
+    /** Full filesystem path to the SKILL.md */
+    path: string;
+}
+/** Structured diff between two agent cards. */
+interface DiffResult {
+    changed: boolean;
+    fields: FieldDiff[];
+    skillsAdded: string[];
+    skillsRemoved: string[];
+    skillsModified: string[];
+}
+/** A single field-level change. */
+interface FieldDiff {
+    field: string;
+    old: unknown;
+    new: unknown;
+}
+/** Result of pushing a branch to a remote. */
+interface PushResult {
+    branch: string;
+    commitHash: string;
+    remoteUrl: string;
+    success: boolean;
+    error?: string;
+}
+/** Result returned by the status command. */
+interface StatusResult {
+    branch: string;
+    publicKey: string;
+    uncommittedChanges: DiffResult | null;
+    branches: Array<{
+        name: string;
+        ahead: number;
+        behind: number;
+    }>;
+}
+
+/**
+ * Compare two agent cards and return a structured diff.
+ */
+declare function diffCards(oldCard: AgentCard, newCard: AgentCard): DiffResult;
+/**
+ * Format a diff result for terminal display.
+ */
+declare function formatDiff(diff: DiffResult): string;
+
+/**
+ * Format a raw base64 public key as the value for the agent card's
+ * `publicKey` field: "ed25519:<base64>".
+ */
+declare function formatPublicKeyField(pubBase64: string): string;
+/**
+ * Extract the raw base64 key from an "ed25519:<base64>" field value.
+ */
+declare function parsePublicKeyField(field: string): string;
+/**
+ * Sign a challenge string with the agent's private key.
+ * Returns a standard base64-encoded signature.
+ */
+declare function signChallenge(nitDir: string, challenge: string): Promise<string>;
+/**
+ * Verify a signature against a challenge using the raw base64 public key.
+ * This is a utility for consumers; nit itself uses it in the remote module
+ * for challenge-response flows.
+ */
+declare function verifySignature(pubBase64: string, challenge: string, signatureBase64: string): boolean;
+
+/**
+ * Fetch an agent card from a remote URL.
+ *
+ * For the main branch, this is a simple public GET.
+ * For other branches, this performs the challenge-response flow:
+ *   1. Request branch → 401 with challenge
+ *   2. Sign challenge with agent's private key
+ *   3. Re-request with signature → get branch card
+ *
+ * @param cardUrl   The agent's card URL (e.g. https://agent-{uuid}.newtype-ai.org)
+ * @param branch    Branch to fetch ("main" for public, others need auth)
+ * @param nitDir    Path to .nit/ directory (needed for signing non-main requests)
+ */
+declare function fetchBranchCard(cardUrl: string, branch: string, nitDir?: string): Promise<AgentCard>;
+
+/**
+ * Walk up from startDir looking for a .nit/ directory.
+ * Returns the path to .nit/ or throws if not found.
+ */
+declare function findNitDir(startDir?: string): string;
+interface InitResult {
+    publicKey: string;
+    cardUrl: string | null;
+    skillsFound: string[];
+}
+/**
+ * Initialize a new nit repository in the project directory.
+ *
+ * 1. Create .nit/ directory structure
+ * 2. Generate Ed25519 keypair
+ * 3. Create or update agent-card.json with publicKey
+ * 4. Create initial commit on main branch
+ */
+declare function init(options?: {
+    projectDir?: string;
+}): Promise<InitResult>;
+/**
+ * Show current branch, uncommitted changes, and ahead/behind remote.
+ */
+declare function status(options?: {
+    projectDir?: string;
+}): Promise<StatusResult>;
+/**
+ * Snapshot the current agent-card.json as a new commit.
+ * Resolves skill pointers from SKILL.md before committing.
+ */
+declare function commit(message: string, options?: {
+    projectDir?: string;
+}): Promise<NitCommit>;
+/**
+ * Walk the commit chain from the current branch HEAD.
+ */
+declare function log(options?: {
+    projectDir?: string;
+    count?: number;
+}): Promise<NitCommit[]>;
+/**
+ * Compare the current card against a target.
+ *
+ * - No target: working card vs HEAD
+ * - Branch name: HEAD vs target branch HEAD
+ * - Commit hash (64 hex chars): HEAD vs specific commit
+ */
+declare function diff(target?: string, options?: {
+    projectDir?: string;
+}): Promise<DiffResult>;
+/**
+ * List branches (no name) or create a new branch (with name).
+ */
+declare function branch(name?: string, options?: {
+    projectDir?: string;
+}): Promise<NitBranch[]>;
+/**
+ * Switch to a different branch. Overwrites agent-card.json with the
+ * branch's version. Aborts if there are uncommitted changes.
+ */
+declare function checkout(branchName: string, options?: {
+    projectDir?: string;
+}): Promise<void>;
+/**
+ * Push current branch (or all branches) to the remote.
+ */
+declare function push(options?: {
+    projectDir?: string;
+    remoteName?: string;
+    all?: boolean;
+}): Promise<PushResult[]>;
+interface RemoteInfo {
+    name: string;
+    url: string;
+    hasCredential: boolean;
+}
+/**
+ * Show remote info. URL comes from agent-card.json, credential from .nit/config.
+ */
+declare function remote(options?: {
+    projectDir?: string;
+}): Promise<RemoteInfo>;
+
+export { type AgentCard, type AgentCardSkill, type DiffResult, type FieldDiff, type InitResult, type NitBranch, type NitCommit, type NitConfig, type NitHead, type NitRemoteConfig, type PushResult, type RemoteInfo, type SkillMetadata, type StatusResult, branch, checkout, commit, diff, diffCards, fetchBranchCard, findNitDir, formatDiff, formatPublicKeyField, init, log, parsePublicKeyField, push, remote, signChallenge, status, verifySignature };

package/dist/index.js

@@ -0,0 +1,39 @@
+// nit — version control for agent cards
+import {
+  branch,
+  checkout,
+  commit,
+  diff,
+  diffCards,
+  fetchBranchCard,
+  findNitDir,
+  formatDiff,
+  formatPublicKeyField,
+  init,
+  log,
+  parsePublicKeyField,
+  push,
+  remote,
+  signChallenge,
+  status,
+  verifySignature
+} from "./chunk-5EGCFUZ7.js";
+export {
+  branch,
+  checkout,
+  commit,
+  diff,
+  diffCards,
+  fetchBranchCard,
+  findNitDir,
+  formatDiff,
+  formatPublicKeyField,
+  init,
+  log,
+  parsePublicKeyField,
+  push,
+  remote,
+  signChallenge,
+  status,
+  verifySignature
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@newtype-ai/nit",
+  "version": "0.1.0",
+  "description": "Version control for agent cards",
+  "type": "module",
+  "bin": {
+    "nit": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "tsup"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-card",
+    "version-control",
+    "nit",
+    "identity",
+    "a2a",
+    "ed25519"
+  ],
+  "author": "newtype-ai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newtype-ai/nit"
+  },
+  "homepage": "https://github.com/newtype-ai/nit",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}