@tanishqkancharla/diffmap 0.1.3 → 0.1.5

package/README.md

@@ -5,34 +5,33 @@
 diffmap is a set of personal skills as well as a web-viewer for Markdown files. It has a unique form of showing diffs using a mixture of callstack diffs and mermaid diagram links, which I've found to be personally extremely helpful in understanding massive diffs.
 
 ```sh
-npx diffmap path/to/file.md
+npx @tanishqkancharla/diffmap serve path/to/file.md
 ```
 
+Bare `npx @tanishqkancharla/diffmap path/to/file.md` is the same as `serve`.
+
 Share a secret gist and print a `diffmap.dev` link (requires [`gh`](https://cli.github.com/) logged in). Does not start a local server:
 
 ```sh
-npx diffmap share path/to.md
+npx @tanishqkancharla/diffmap share path/to.md
 ```
 
 Hosted viewer: `https://diffmap.dev/g/<gistId>` (optional `/<file.md>`; `#heading` is the table of contents). The page fetches the gist in the browser from `api.github.com`. Gists are unlisted, not private.
 
 ## Agent skills
 
-Install skills from this repository:
-
 ```sh
-npx skills add tanishqkancharla/diffmap --skill code-walkthrough
 npx skills add tanishqkancharla/diffmap --skill generate-spec
 ```
 
-`code-walkthrough` explains landed changes. `generate-spec` writes a phased spec for work that has not happened yet, then serves `specs/<name>.md` with diffmap.
+Keeps a spec in `specs/` that stays true to what's planned versus already in the tree. Serve it with diffmap. Share from a GitHub PR (`https://diffmap.dev/<owner>/<repo>/pull/<n>/specs/<name>.md`) or `npx @tanishqkancharla/diffmap share`.
 
 Options:
 
-- `--port <n>` — listen port (default `4177`)
+- `--port <n>` — pin a listen port (default: a free port)
 - `--root <dir>` — workspace root for file excerpts (default the directory you ran the command from)
 
-**Done** in the top right stops the server.
+**Close server** in the top right stops the server. Hosted gist and GitHub viewers have no local server, so they omit this control.
 
 The server also stops after 24 hours without a page or source request.
 Loading or refreshing the page resets the timer; background health checks and
@@ -41,23 +40,35 @@ Vite connections do not keep it alive.
 List every running viewer, including viewers using custom ports:
 
 ```sh
-npx diffmap list
+npx @tanishqkancharla/diffmap list
 ```
 
+Update a global install to the latest `@tanishqkancharla/diffmap` on npm. `diffmap --update` does the same thing:
+
+```sh
+diffmap update
+```
+
+If you are already on the latest version, it says so and exits. Otherwise it runs the global install for the package manager that installed diffmap (`npm install --global`, `pnpm add --global`, or `bun add --global`) and prints the old and new versions. Under `npx`, or when it cannot tell how diffmap was installed, it prints the command to run instead of installing anything.
+
 Request the page with `Accept: text/markdown` to read the current source file
-instead of the rendered HTML:
+instead of the rendered HTML. Use the URL printed by `serve`:
 
 ```sh
-curl -H 'Accept: text/markdown' http://127.0.0.1:4177/
+curl -H 'Accept: text/markdown' http://127.0.0.1:<port>/
 ```
 
 ## Library
 
 ```ts
-import { startServer, parseFence, parseViewerDocument } from "diffmap";
+import {
+  startServer,
+  parseFence,
+  parseViewerDocument,
+} from "@tanishqkancharla/diffmap";
 ```
 
-`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-spec and code-walkthrough skills own spec vs walkthrough section order; the viewer does not.
+`parseViewerDocument` turns markdown into the page document with [md4x](https://github.com/unjs/md4x). `startServer` listens. The generate-spec skill owns document shape; the viewer does not.
 
 ## Fences
 
@@ -176,7 +187,7 @@ Resolution uses the workspace's TypeScript configuration and current files.
 Deleted files and lines that no longer match the workspace show a message;
 their call stack references still highlight the embedded old-side diff.
 
-Run `npx diffmap fixtures/annotations.md` for an example
+Run `npx @tanishqkancharla/diffmap fixtures/annotations.md` for an example
 with old/new references, multiple files, and unchanged context.
 
 ## Link Mermaid nodes and edges

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanishqkancharla/diffmap",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Serve a spec or code walkthrough as a local page",
   "license": "MIT",
   "author": "Tanishq Kancharla",
@@ -33,7 +33,7 @@
     "lint:fix": "oxlint --fix src vite.config.ts vite.gist.config.ts bin.js",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run format:check",
     "release": "npm publish",
-    "test": "tsx --test src/gist/route.test.ts",
+    "test": "tsx --test src/cli.test.ts src/update.test.ts src/parseViewer.test.ts src/serve.test.ts src/gist/route.test.ts src/github/route.test.ts src/github/patch.test.ts src/github/fetchRepo.test.ts src/viewer/sourceHeader.test.ts src/host/home.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "vite build",
     "build:gist": "vite build",
@@ -45,7 +45,7 @@
     "beautiful-mermaid": "^1.1.3",
     "errore": "^0.14.1",
     "incur": "^0.4.20",
-    "maui": "npm:@tanishqkancharla/maui@0.0.16",
+    "maui": "npm:@tanishqkancharla/maui@0.0.30",
     "md4x": "^0.0.29",
     "purse-styles": "^0.2.3",
     "react": "^19.2.8",

package/src/cli.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import test from "node:test";
+
+const execFileAsync = promisify(execFile);
+const srcDir = fileURLToPath(new URL(".", import.meta.url));
+const packageRoot = path.resolve(srcDir, "..");
+const cliPath = path.join(srcDir, "cli.ts");
+
+async function runCli(args: string[]) {
+  try {
+    const result = await execFileAsync(
+      process.execPath,
+      ["--import", "tsx", cliPath, ...args],
+      {
+        cwd: packageRoot,
+        timeout: 20_000,
+        maxBuffer: 1_000_000,
+      },
+    );
+    return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (cause) {
+    if (typeof cause !== "object" || !cause) throw cause;
+    const exitCode =
+      "code" in cause && typeof cause.code === "number"
+        ? cause.code
+        : undefined;
+    const stdout =
+      "stdout" in cause && typeof cause.stdout === "string" ? cause.stdout : "";
+    const stderr =
+      "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr : "";
+    return { exitCode, stdout, stderr };
+  }
+}
+
+test("diffmap --version matches package.json", async () => {
+  const pkg = JSON.parse(
+    await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+  ) as { version: string };
+  const source = await fs.readFile(cliPath, "utf8");
+  assert.doesNotMatch(source, /version:\s*["'`]\d+\.\d+\.\d+/);
+  const result = await runCli(["--version"]);
+  assert.equal(result.exitCode, 0, result.stderr);
+  const printed = `${result.stdout}${result.stderr}`.trim();
+  assert.equal(printed, pkg.version);
+});

package/src/cli.ts

@@ -2,44 +2,120 @@
 
 import { Cli, z } from "incur";
 import { resolveFromInvokeCwd } from "./invokeCwd.js";
+import { packageVersion } from "./packageVersion.js";
 import { listRunningDiffmaps } from "./registry.js";
 import { startServer } from "./serve.js";
 import { shareMarkdownFile } from "./share.js";
+import {
+  detectInstallMethod,
+  fetchLatestVersion,
+  packageName,
+  resolveUpdateArgv,
+  runCommand,
+  runUpdate,
+} from "./update.js";
 
-const cli = Cli.create("diffmap", {
-  description: "Serve a spec or code walkthrough as a local page",
-  version: "0.1.3",
-  args: z.object({
-    file: z.string().describe("Path to the markdown file"),
-  }),
-  options: z.object({
-    port: z.coerce.number().optional().describe("Port (default 4177)"),
-    root: z.string().optional().describe("Workspace root for file excerpts"),
-  }),
-  output: z.object({
-    url: z.string(),
-    file: z.string(),
-  }),
-  async *run(c) {
-    const started = await startServer({
-      filePath: resolveFromInvokeCwd(c.args.file),
-      workspaceRoot:
-        c.options.root === undefined
-          ? resolveFromInvokeCwd(".")
-          : resolveFromInvokeCwd(c.options.root),
-      port: c.options.port === undefined ? 4177 : c.options.port,
+const serveArgs = z.object({
+  file: z.string().describe("Path to the markdown file"),
+});
+
+const serveOptions = z.object({
+  port: z.coerce.number().optional().describe("Port (default: a free port)"),
+  root: z.string().optional().describe("Workspace root for file excerpts"),
+});
+
+const serveOutput = z.object({
+  url: z.string(),
+  file: z.string(),
+});
+
+type ServeContext = {
+  args: { file: string };
+  options: { port?: number | undefined; root?: string | undefined };
+  error: (input: { code: string; message: string }) => never;
+};
+
+async function* runServe(c: ServeContext) {
+  const started = await startServer({
+    filePath: resolveFromInvokeCwd(c.args.file),
+    workspaceRoot:
+      c.options.root === undefined
+        ? resolveFromInvokeCwd(".")
+        : resolveFromInvokeCwd(c.options.root),
+    port: c.options.port,
+  });
+  if (started instanceof Error) {
+    return c.error({
+      code: "DIFFMAP",
+      message: started.message,
     });
-    if (started instanceof Error) {
-      return c.error({
-        code: "DIFFMAP",
-        message: started.message,
-      });
-    }
-    yield { url: started.url, file: started.filePath };
-    await started.closed;
-    return { url: started.url, file: started.filePath };
-  },
+  }
+  yield { url: started.url, file: started.filePath };
+  await started.closed;
+  return { url: started.url, file: started.filePath };
+}
+
+const cli = Cli.create("diffmap", {
+  description: "Serve a spec locally, or share it as a gist",
+  version: packageVersion,
+  args: serveArgs,
+  options: serveOptions,
+  output: serveOutput,
+  hint: "`serve <spec.md>` runs the local viewer. `share <spec.md>` publishes a secret gist. `update` (or `--update`) installs the latest diffmap.",
+  examples: [
+    {
+      args: { file: "spec.md" },
+      description: "Same as `diffmap serve spec.md`",
+    },
+  ],
+  run: runServe,
 })
+  .command("serve", {
+    description: "Run the local viewer server",
+    args: serveArgs,
+    options: serveOptions,
+    output: serveOutput,
+    examples: [
+      {
+        args: { file: "spec.md" },
+        description: "Open the local viewer",
+      },
+    ],
+    run: runServe,
+  })
+  .command("share", {
+    description: "Publish a secret gist and print https://diffmap.dev/g/<id>",
+    args: z.object({
+      file: z.string().describe("Path to the markdown file"),
+    }),
+    options: z.object({
+      public: z.boolean().optional().describe("Create a public gist"),
+    }),
+    output: z.object({
+      gistId: z.string(),
+      gistUrl: z.string(),
+      viewerUrl: z.string(),
+    }),
+    examples: [
+      {
+        args: { file: "spec.md" },
+        description: "Secret gist → https://diffmap.dev/g/<id>",
+      },
+    ],
+    async run(c) {
+      const shared = await shareMarkdownFile({
+        filePath: resolveFromInvokeCwd(c.args.file),
+        isPublic: c.options.public === true,
+      });
+      if (shared instanceof Error) {
+        return c.error({
+          code: "DIFFMAP",
+          message: shared.message,
+        });
+      }
+      return c.ok(shared);
+    },
+  })
   .command("list", {
     description: "List running diffmap viewers",
     output: z.object({
@@ -63,32 +139,31 @@ const cli = Cli.create("diffmap", {
       return c.ok({ instances });
     },
   })
-  .command("share", {
-    description: "Upload a walkthrough gist and print the diffmap.dev URL",
-    args: z.object({
-      file: z.string().describe("Path to the markdown file"),
-    }),
-    options: z.object({
-      public: z.boolean().optional().describe("Create a public gist"),
-    }),
+  .command("update", {
+    description: `Update diffmap to the latest ${packageName} on npm (same as --update)`,
     output: z.object({
-      gistId: z.string(),
-      gistUrl: z.string(),
-      viewerUrl: z.string(),
+      status: z.enum(["up-to-date", "updated", "manual"]),
+      message: z.string(),
+      current: z.string(),
+      previous: z.string().optional(),
+      latest: z.string().optional(),
+      command: z.string().optional(),
     }),
     async run(c) {
-      const shared = await shareMarkdownFile({
-        filePath: resolveFromInvokeCwd(c.args.file),
-        isPublic: c.options.public === true,
+      const result = await runUpdate({
+        currentVersion: packageVersion,
+        fetchLatestVersion,
+        detectInstallMethod,
+        runCommand,
       });
-      if (shared instanceof Error) {
+      if (result instanceof Error) {
         return c.error({
-          code: "DIFFMAP",
-          message: shared.message,
+          code: "UPDATE_FAILED",
+          message: result.message,
         });
       }
-      return c.ok(shared);
+      return c.ok(result);
     },
   });
 
-await cli.serve();
+await cli.serve(resolveUpdateArgv(process.argv.slice(2)));

package/src/contentPlugin.ts

@@ -15,9 +15,11 @@ export function diffmapContentPlugin(input: {
     async load(id) {
       if (id !== virtualId) return;
       const source = await fs.readFile(input.filePath, "utf8");
-      const document = parseViewerDocument(source);
-      if (document instanceof Error) throw document;
-      return `export const viewerDocument = ${JSON.stringify(document)};`;
+      const document = parseViewerDocument(source, input.filePath);
+      if (document instanceof Error) {
+        return `export const viewerDocument = null; export const parseError = ${JSON.stringify(document.message)};`;
+      }
+      return `export const viewerDocument = ${JSON.stringify(document)}; export const parseError = null;`;
     },
     transformIndexHtml(html) {
       return html.replaceAll(

package/src/errors.ts

@@ -17,7 +17,7 @@ export class DiffmapRegistryError extends errore.createTaggedError({
 
 export class DiffmapMermaidError extends errore.createTaggedError({
   name: "DiffmapMermaidError",
-  message: "diffmap could not render mermaid",
+  message: "diffmap could not parse mermaid in $path ($where): $reason",
 }) {}
 
 export class DiffmapParseError extends errore.createTaggedError({
@@ -39,3 +39,8 @@ export class DiffmapShareError extends errore.createTaggedError({
   name: "DiffmapShareError",
   message: "diffmap share failed: $reason",
 }) {}
+
+export class DiffmapUpdateError extends errore.createTaggedError({
+  name: "DiffmapUpdateError",
+  message: "diffmap update failed: $reason",
+}) {}

package/src/gist/GistApp.tsx

@@ -6,7 +6,9 @@ import { parseViewerDocument } from "../parseViewer.ts";
 import type { ViewerDocument } from "../parseViewer.ts";
 import { ViewerApp } from "../viewer/ViewerApp.tsx";
 import { loadGistMarkdown, type GistDocument } from "./fetchGist.ts";
-import { GistLanding, GistLoading, GistStatus } from "./GistStatus.tsx";
+import { GistPinContext } from "./pin.ts";
+import { HostHome } from "../host/HostHome.tsx";
+import { GistLoading, GistStatus } from "./GistStatus.tsx";
 import {
   gistPath,
   parseGistPath,
@@ -82,7 +84,7 @@ export function GistApp() {
     return () => abort.abort();
   }, [route]);
 
-  if (route.kind === "home") return <GistLanding />;
+  if (route.kind === "home") return <HostHome />;
   if (route.kind === "invalid") {
     return (
       <GistStatus title="Not a gist id">
@@ -151,24 +153,32 @@ export function GistApp() {
   }
 
   return (
-    <ViewerApp
-      key={`${view.gist.id}:${view.file}`}
-      document={view.document}
-      mode="gist"
-      headerActions={
-        <GistHeader
-          gistId={view.gist.id}
-          htmlUrl={view.gist.htmlUrl}
-          files={view.gist.files}
-          current={view.file}
-          onSelect={(file) => {
-            const next = gistPath(view.gist.id, file);
-            window.history.pushState({}, "", next);
-            setRoute(parseGistPath(next));
-          }}
-        />
-      }
-    />
+    <GistPinContext.Provider
+      value={{
+        gistId: view.gist.id,
+        file: view.file,
+        htmlUrl: view.gist.htmlUrl,
+      }}
+    >
+      <ViewerApp
+        key={`${view.gist.id}:${view.file}`}
+        document={view.document}
+        mode="gist"
+        headerActions={
+          <GistHeader
+            gistId={view.gist.id}
+            htmlUrl={view.gist.htmlUrl}
+            files={view.gist.files}
+            current={view.file}
+            onSelect={(file) => {
+              const next = gistPath(view.gist.id, file);
+              window.history.pushState({}, "", next);
+              setRoute(parseGistPath(next));
+            }}
+          />
+        }
+      />
+    </GistPinContext.Provider>
   );
 }
 
@@ -196,7 +206,10 @@ async function loadView(
       file: file ?? "",
     };
   }
-  const parsed = parseViewerDocument(loaded.gist.chosen.content);
+  const parsed = parseViewerDocument(
+    loaded.gist.chosen.content,
+    loaded.gist.chosen.name,
+  );
   if (parsed instanceof Error) {
     return {
       kind: "parse-error",

package/src/gist/GistStatus.tsx

@@ -19,6 +19,7 @@ export function GistStatus(props: {
   children: ReactNode;
   gistId?: string;
   gistUrl?: string;
+  linkLabel?: string;
 }) {
   const shell = useStyles(styles.shell);
   const header = useStyles(styles.header);
@@ -39,7 +40,9 @@ export function GistStatus(props: {
         {props.children}
         {gistUrl !== undefined && (
           <P>
-            <Link href={gistUrl}>Open gist on GitHub</Link>
+            <Link href={gistUrl}>
+              {props.linkLabel ?? "Open gist on GitHub"}
+            </Link>
           </P>
         )}
       </main>
@@ -47,10 +50,10 @@ export function GistStatus(props: {
   );
 }
 
-export function GistLoading() {
+export function GistLoading(props: { title?: string }) {
   const row = useStyles(styles.loading);
   return (
-    <GistStatus title="Loading gist…">
+    <GistStatus title={props.title ?? "Loading gist…"}>
       <div className={row}>
         <Thinking />
       </div>
@@ -58,41 +61,6 @@ export function GistLoading() {
   );
 }
 
-export function GistLanding() {
-  const code = useStyles(styles.code);
-  return (
-    <GistStatus title="diffmap">
-      <P>
-        A hosted viewer for diffmap walkthroughs. This page fetches a GitHub
-        gist in your browser. There is no server holding the markdown.
-      </P>
-      <P>
-        Canonical URL:{" "}
-        <code className={code}>https://diffmap.dev/g/&lt;gistId&gt;</code>.
-        Optional file:{" "}
-        <code className={code}>/g/&lt;gistId&gt;/&lt;file.md&gt;</code>. Heading
-        hashes stay in the fragment, same as the local viewer.
-      </P>
-      <P>
-        Share a secret gist (requires <code className={code}>gh</code>
-        ):
-      </P>
-      <P>
-        <code className={code}>npx diffmap share path/to.md</code>
-      </P>
-      <P>
-        Secret gists are unlisted, not private. Anyone with the id can read
-        them. Unauthenticated GitHub API is 60 requests per hour per IP.
-      </P>
-      <P>
-        <Link href="https://github.com/tanishqkancharla/diffmap">
-          tanishqkancharla/diffmap
-        </Link>
-      </P>
-    </GistStatus>
-  );
-}
-
 const styles = {
   shell: style(flex({ direction: "column" }), {
     width: "100%",
@@ -103,7 +71,7 @@ const styles = {
     backgroundColor: colors.gray[4],
   }),
   header: style(
-    flex({ direction: "row", align: "center", justify: "between" }),
+    flex({ direction: "row", alignItems: "center", justifyContent: "between" }),
     spacing.padding({ x: 6, y: 3 }),
     flexItem({ size: "hug" }),
     border(["bottom"], "border"),
@@ -128,10 +96,7 @@ const styles = {
   title: style(text({ size: "xl", fontWeight: 600, color: "highContrast" }), {
     marginBottom: spacing.value(4),
   }),
-  loading: style(flex({ direction: "row", align: "center" }), {
+  loading: style(flex({ direction: "row", alignItems: "center" }), {
     minHeight: spacing.value(12),
   }),
-  code: style(text({ size: "sm", color: "highContrast" }), {
-    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
-  }),
 };

package/src/gist/main.tsx

@@ -2,7 +2,7 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { MauiProvider } from "maui";
 import { rewritePiGistUrl } from "./route.ts";
-import { GistApp } from "./GistApp.tsx";
+import { HostApp } from "../host/HostApp.tsx";
 import "../viewer/styles.css";
 
 const rewritten = rewritePiGistUrl(
@@ -19,7 +19,7 @@ if (root === null) throw new Error("diffmap root element is missing");
 createRoot(root).render(
   <StrictMode>
     <MauiProvider>
-      <GistApp />
+      <HostApp />
     </MauiProvider>
   </StrictMode>,
 );

package/src/gist/pin.ts

@@ -0,0 +1,14 @@
+import { createContext, useContext } from "react";
+
+/** Gist snapshot: identify the gist file, never a fake owner/repo. */
+export type GistPin = {
+  gistId: string;
+  file: string;
+  htmlUrl: string;
+};
+
+export const GistPinContext = createContext<GistPin | undefined>(undefined);
+
+export function useGistPin() {
+  return useContext(GistPinContext);
+}