@tanishqkancharla/diffmap 0.1.4 → 0.2.0

package/src/cli.ts

@@ -2,16 +2,25 @@
 
 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 serveArgs = z.object({
   file: z.string().describe("Path to the markdown file"),
 });
 
 const serveOptions = z.object({
-  port: z.coerce.number().optional().describe("Port (default 4177)"),
+  port: z.coerce.number().optional().describe("Port (default: a free port)"),
   root: z.string().optional().describe("Workspace root for file excerpts"),
 });
 
@@ -33,7 +42,7 @@ async function* runServe(c: ServeContext) {
       c.options.root === undefined
         ? resolveFromInvokeCwd(".")
         : resolveFromInvokeCwd(c.options.root),
-    port: c.options.port === undefined ? 4177 : c.options.port,
+    port: c.options.port,
   });
   if (started instanceof Error) {
     return c.error({
@@ -48,11 +57,11 @@ async function* runServe(c: ServeContext) {
 
 const cli = Cli.create("diffmap", {
   description: "Serve a spec locally, or share it as a gist",
-  version: "0.1.3",
+  version: packageVersion,
   args: serveArgs,
   options: serveOptions,
   output: serveOutput,
-  hint: "`serve <spec.md>` runs the local viewer. `share <spec.md>` publishes a secret gist.",
+  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" },
@@ -96,6 +105,7 @@ const cli = Cli.create("diffmap", {
     async run(c) {
       const shared = await shareMarkdownFile({
         filePath: resolveFromInvokeCwd(c.args.file),
+        workspaceRoot: resolveFromInvokeCwd("."),
         isPublic: c.options.public === true,
       });
       if (shared instanceof Error) {
@@ -129,6 +139,32 @@ const cli = Cli.create("diffmap", {
       }
       return c.ok({ instances });
     },
+  })
+  .command("update", {
+    description: `Update diffmap to the latest ${packageName} on npm (same as --update)`,
+    output: z.object({
+      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 result = await runUpdate({
+        currentVersion: packageVersion,
+        fetchLatestVersion,
+        detectInstallMethod,
+        runCommand,
+      });
+      if (result instanceof Error) {
+        return c.error({
+          code: "UPDATE_FAILED",
+          message: result.message,
+        });
+      }
+      return c.ok(result);
+    },
   });
 
-await cli.serve();
+await cli.serve(resolveUpdateArgv(process.argv.slice(2)));

package/src/errors.ts

@@ -30,6 +30,11 @@ export class DiffmapAnnotationError extends errore.createTaggedError({
   message: "diffmap source annotation: $reason",
 }) {}
 
+export class DiffmapGitError extends errore.createTaggedError({
+  name: "DiffmapGitError",
+  message: "$reason",
+}) {}
+
 export class DiffmapDefinitionError extends errore.createTaggedError({
   name: "DiffmapDefinitionError",
   message: "$reason",
@@ -39,3 +44,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

@@ -4,10 +4,16 @@ import { style, useStyles } from "purse-styles";
 import { init } from "md4x/standalone";
 import { parseViewerDocument } from "../parseViewer.ts";
 import type { ViewerDocument } from "../parseViewer.ts";
+import { WORKING } from "../changes.ts";
+import {
+  ChangesLoaderContext,
+  type ChangesLoader,
+} from "../viewer/changesSource.ts";
 import { ViewerApp } from "../viewer/ViewerApp.tsx";
 import { loadGistMarkdown, type GistDocument } from "./fetchGist.ts";
 import { GistPinContext } from "./pin.ts";
-import { GistLanding, GistLoading, GistStatus } from "./GistStatus.tsx";
+import { HostHome } from "../host/HostHome.tsx";
+import { GistLoading, GistStatus } from "./GistStatus.tsx";
 import {
   gistPath,
   parseGistPath,
@@ -40,6 +46,7 @@ type GistView =
       gist: GistDocument;
       file: string;
       document: ViewerDocument;
+      loadChanges: ChangesLoader;
     };
 
 export function GistApp() {
@@ -83,7 +90,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">
@@ -159,24 +166,26 @@ export function GistApp() {
         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));
-            }}
-          />
-        }
-      />
+      <ChangesLoaderContext.Provider value={view.loadChanges}>
+        <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));
+              }}
+            />
+          }
+        />
+      </ChangesLoaderContext.Provider>
     </GistPinContext.Provider>
   );
 }
@@ -217,11 +226,21 @@ async function loadView(
       message: parsed.message,
     };
   }
+  const snapshot = loaded.gist.changes;
   return {
     kind: "ready",
     gist: loaded.gist,
     file: loaded.gist.chosen.name,
     document: parsed,
+    loadChanges: (rev) =>
+      Promise.resolve(
+        snapshot[rev] ??
+          new Error(
+            rev === WORKING
+              ? "Uncommitted changes are only available in a local viewer."
+              : `This gist has no snapshot of ${rev}. Share the spec again with diffmap share.`,
+          ),
+      ),
   };
 }
 

package/src/gist/GistStatus.tsx

@@ -61,52 +61,6 @@ export function GistLoading(props: { title?: string }) {
   );
 }
 
-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 or a public repo file in your browser. There is no server holding
-        the markdown.
-      </P>
-      <P>
-        Canonical gist 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>. GitHub
-        spec:{" "}
-        <code className={code}>
-          https://diffmap.dev/&lt;owner&gt;/&lt;repo&gt;/pull/&lt;n&gt;/&lt;path.md&gt;
-        </code>{" "}
-        or{" "}
-        <code className={code}>
-          /&lt;owner&gt;/&lt;repo&gt;/commit/&lt;sha&gt;/&lt;path.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 @tanishqkancharla/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%",
@@ -117,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"),
@@ -142,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/fetchGist.ts

@@ -1,3 +1,4 @@
+import { GIST_CHANGES_FILE, type Changes, type Rev } from "../changes.ts";
 import { githubGistUrl, markdownFileNames, pickMarkdownFile } from "./route.ts";
 
 export type GistMarkdownFile = {
@@ -10,6 +11,8 @@ export type GistDocument = {
   htmlUrl: string;
   files: GistMarkdownFile[];
   chosen: GistMarkdownFile;
+  /** Snapshot `diffmap share` saved for each commit the spec references. */
+  changes: Record<Rev, Changes>;
 };
 
 export type GistLoadResult =
@@ -95,6 +98,25 @@ export async function loadGistMarkdown(
     return { status: "missing-file", htmlUrl, files };
   }
 
+  const snapshotFile = apiFiles[GIST_CHANGES_FILE];
+  const snapshot =
+    snapshotFile === undefined
+      ? "{}"
+      : await readGistFile(snapshotFile, signal);
+  if (snapshot instanceof Error) {
+    return { status: "error", message: snapshot.message };
+  }
+  let changes: Record<Rev, Changes>;
+  try {
+    // SAFETY: diffmap share writes this file from readDocumentChanges.
+    changes = JSON.parse(snapshot) as Record<Rev, Changes>;
+  } catch {
+    return {
+      status: "error",
+      message: `${GIST_CHANGES_FILE} is not valid JSON.`,
+    };
+  }
+
   return {
     status: "ok",
     gist: {
@@ -102,6 +124,7 @@ export async function loadGistMarkdown(
       htmlUrl,
       files,
       chosen,
+      changes,
     },
   };
 }