peakurl 0.0.3 → 0.1.1

package/README.md

@@ -1,124 +1,132 @@
 # PeakURL CLI
 
-`peakurl` is the official command-line interface for PeakURL.
+The official command-line interface for PeakURL.
+
+Use `peakurl` to create short links, inspect existing links, and manage your PeakURL account from the terminal.
 
 ## Install
 
+Node.js 20 or later is required.
+
 ```bash
 npm install -g peakurl
 ```
 
-The npm package name is unscoped and the executable is also `peakurl`.
-
-## Authentication
+## Quick Start
 
-The CLI uses a PeakURL API key and validates it with `GET /api/v1/users/me` before storing it.
-PeakURL API keys are opaque 48-character hex bearer tokens, for example `0123456789abcdef0123456789abcdef0123456789abcdef`.
-The CLI accepts either the site root URL such as `https://peakurl.org` or the dashboard-exposed API base URL such as `https://peakurl.org/api/v1`.
+Sign in with your PeakURL API key:
 
 ```bash
-peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
+peakurl login \
+    --base-url https://peakurl.org \
+    --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
-You can also provide credentials through environment variables, which is useful in CI:
+Create and review a short link:
 
 ```bash
-export PEAKURL_BASE_URL=https://peakurl.org
-export PEAKURL_API_KEY=0123456789abcdef0123456789abcdef0123456789abcdef
+peakurl create \
+    https://example.com/articles/launch \
+    --alias launch \
+    --title "Launch Post"
+
+peakurl list
+peakurl whoami
 ```
 
-Stored credentials live in the OS-standard per-user config directory for `peakurl`.
+## Authentication
 
-## Commands
+The CLI uses PeakURL bearer API keys and validates them against `GET /api/v1/users/me` before saving credentials.
 
-### `peakurl login`
+- `--base-url` accepts either the site root, such as `https://peakurl.org`, or the API base URL, such as `https://peakurl.org/api/v1`
+- API keys are opaque 48-character hex tokens
+- Credentials are stored in the standard per-user config location for `peakurl`
+
+For CI or automation, you can also authenticate with environment variables:
 
 ```bash
-peakurl login --base-url https://peakurl.org --api-key 0123456789abcdef0123456789abcdef0123456789abcdef
+export PEAKURL_BASE_URL=https://peakurl.org
+export PEAKURL_API_KEY=0123456789abcdef0123456789abcdef0123456789abcdef
 ```
 
-### `peakurl whoami`
+## Commands
 
-```bash
-peakurl whoami
-peakurl whoami --json
-```
+| Command                        | Description                                                |
+| ------------------------------ | ---------------------------------------------------------- |
+| `peakurl login`                | Validate and save your PeakURL credentials.                |
+| `peakurl whoami`               | Show the current authenticated account.                    |
+| `peakurl create <url>`         | Create a new short link.                                   |
+| `peakurl list`                 | List links in your account.                                |
+| `peakurl get <id-or-alias>`    | Fetch a single link by ID or alias.                        |
+| `peakurl delete <id-or-alias>` | Delete a link by ID or alias.                              |
+| `peakurl update`               | Show the latest available CLI version and install command. |
 
-### `peakurl create <url>`
+## Examples
+
+Create a short link:
 
 ```bash
-peakurl create https://example.com/articles/launch --alias launch --title "Launch Post"
-peakurl create https://example.com --json
+peakurl create \
+    https://example.com \
+    --alias example \
+    --title "Example"
 ```
 
-### `peakurl list`
+List links as JSON:
 
 ```bash
-peakurl list
-peakurl list --search launch --limit 10 --json
+peakurl list \
+    --limit 10 \
+    --json
 ```
 
-### `peakurl get <id-or-alias>`
+Inspect a link:
 
 ```bash
-peakurl get launch
-peakurl get 681f3b63e7e44c0a1e83aa11 --json
+peakurl get example
 ```
 
-### `peakurl delete <id-or-alias>`
+Delete a link:
 
 ```bash
-peakurl delete launch
-peakurl delete 681f3b63e7e44c0a1e83aa11 --quiet
+peakurl delete example
 ```
 
-When you pass an alias or short code to `delete`, the CLI resolves it to the
-stable PeakURL row ID first because the current backend delete route operates on
-IDs.
-
-## Flags
+When `delete` receives an alias or short code, the CLI resolves it to the underlying PeakURL row ID before deleting it.
 
-Common flags:
+Check the latest available CLI version:
 
-- `--json` prints machine-readable output.
-- `--quiet` prints minimal output for scripts.
+```bash
+peakurl update --check
+```
 
-Create flags:
+Show the recommended install command:
 
-- `--alias`
-- `--title`
-- `--password`
-- `--status`
-- `--expires-at`
-- `--utm-source`
-- `--utm-medium`
-- `--utm-campaign`
-- `--utm-term`
-- `--utm-content`
+```bash
+peakurl update
+```
 
-List flags:
+Install the latest version manually:
 
-- `--page`
-- `--limit`
-- `--search`
-- `--sort-by`
-- `--sort-order`
+```bash
+npm install -g peakurl@latest
+```
 
-## Development
+Disable update notices in the current shell:
 
 ```bash
-npm install
-npm run build
-npm run typecheck
-npm test
+export PEAKURL_DISABLE_UPDATE_CHECK=1
 ```
 
-Production builds emit the published executable at `bin/peakurl.js`.
+## Output
 
-## Release
+- Human-readable output is the default
+- `--json` prints machine-readable JSON where supported
+- `--quiet` minimizes output for scripts
 
-GitHub Actions publishes the CLI to the public npm registry when a GitHub
-Release is published.
+## Links
 
-The workflow expects a repository secret named `NPM_TOKEN` and publishes to
-`https://registry.npmjs.org/` with provenance enabled.
+- Website: <https://peakurl.org/>
+- API docs: <https://peakurl.org/docs/api>
+- npm package: <https://www.npmjs.com/package/peakurl>
+- Issues: <https://github.com/PeakURL/PeakURL-CLI/issues>

package/bin/peakurl.js

@@ -234,9 +234,18 @@ import { chmod, mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join } from "path";
 import envPaths from "env-paths";
 var CONFIG_FILENAME = "config.json";
+var STATE_FILENAME = "state.json";
 function defaultConfigPath() {
   return join(envPaths("peakurl", { suffix: "" }).config, CONFIG_FILENAME);
 }
+function defaultStatePath() {
+  return join(envPaths("peakurl", { suffix: "" }).config, STATE_FILENAME);
+}
+async function ensureParentDirectory(filePath) {
+  const directory = dirname(filePath);
+  await mkdir(directory, { recursive: true, mode: 448 });
+  return directory;
+}
 var ConfigStore = class {
   filePath;
   /**
@@ -292,8 +301,7 @@ var ConfigStore = class {
    * @param config Normalized credential set to write.
    */
   async save(config) {
-    const directory = dirname(this.filePath);
-    await mkdir(directory, { recursive: true, mode: 448 });
+    const directory = await ensureParentDirectory(this.filePath);
     await writeFile(this.filePath, `${JSON.stringify(config, null, 2)}
 `, {
       mode: 384
@@ -305,6 +313,46 @@ var ConfigStore = class {
     }
   }
 };
+var StateStore = class {
+  filePath;
+  /**
+   * Creates a state store bound to one on-disk file.
+   *
+   * @param filePath Optional override used by tests or advanced callers.
+   */
+  constructor(filePath = defaultStatePath()) {
+    this.filePath = filePath;
+  }
+  /**
+   * Loads cached state from disk.
+   *
+   * Missing or invalid files are treated as empty state because the CLI can
+   * always recompute update metadata on the next successful network check.
+   *
+   * @returns Parsed state object or an empty object.
+   */
+  async load() {
+    try {
+      const content = await readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(content);
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * Persists cached state to disk.
+   *
+   * @param state State payload to save.
+   */
+  async save(state) {
+    await ensureParentDirectory(this.filePath);
+    await writeFile(this.filePath, `${JSON.stringify(state, null, 2)}
+`, {
+      mode: 384
+    });
+  }
+};
 
 // src/lib/auth.ts
 function resolveLoginConfig(input, env) {
@@ -476,6 +524,47 @@ function writeStderr(message = "") {
   process.stderr.write(`${message}
 `);
 }
+function writeNoticeBox(title, lines, target = "stderr") {
+  const contentLines = lines.length > 0 ? lines : [""];
+  const width = Math.max(
+    title.length,
+    ...contentLines.map((line) => line.length)
+  );
+  const stream = target === "stdout" ? process.stdout : process.stderr;
+  const useTuiBox = stream.isTTY;
+  const border = useTuiBox ? {
+    topLeft: "\u250C",
+    topRight: "\u2510",
+    bottomLeft: "\u2514",
+    bottomRight: "\u2518",
+    horizontal: "\u2500",
+    vertical: "\u2502",
+    separatorLeft: "\u251C",
+    separatorRight: "\u2524"
+  } : {
+    topLeft: "+",
+    topRight: "+",
+    bottomLeft: "+",
+    bottomRight: "+",
+    horizontal: "-",
+    vertical: "|",
+    separatorLeft: "+",
+    separatorRight: "+"
+  };
+  const topBorder = `${border.topLeft}${border.horizontal.repeat(width + 2)}${border.topRight}`;
+  const separator = `${border.separatorLeft}${border.horizontal.repeat(width + 2)}${border.separatorRight}`;
+  const bottomBorder = `${border.bottomLeft}${border.horizontal.repeat(width + 2)}${border.bottomRight}`;
+  const writeLine = target === "stdout" ? writeStdout : writeStderr;
+  writeLine(topBorder);
+  writeLine(`${border.vertical} ${title.padEnd(width)} ${border.vertical}`);
+  writeLine(separator);
+  for (const line of contentLines) {
+    writeLine(
+      `${border.vertical} ${line.padEnd(width)} ${border.vertical}`
+    );
+  }
+  writeLine(bottomBorder);
+}
 function writeJson(value) {
   writeStdout(JSON.stringify(value, null, 2));
 }
@@ -633,6 +722,244 @@ async function loginCommand(options) {
   writeStdout(formatUserDetails(response.data));
 }
 
+// src/lib/update.ts
+var PACKAGE_NAME = "peakurl";
+var DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+var CACHE_TTL_MS = 1e3 * 60 * 60 * 12;
+var NOTICE_TTL_MS = 1e3 * 60 * 60 * 24;
+function readTimestamp(value) {
+  if (!value) {
+    return null;
+  }
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+function getRegistryUrl(env) {
+  return env.PEAKURL_NPM_REGISTRY_URL?.trim() || DEFAULT_REGISTRY_URL;
+}
+function normalizeRegistryUrl(registryUrl) {
+  return registryUrl.replace(/\/+$/, "");
+}
+function parseSemver(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    version
+  );
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prerelease: match[4] ? match[4].split(".") : []
+  };
+}
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) {
+    return 0;
+  }
+  if (left.length === 0) {
+    return 1;
+  }
+  if (right.length === 0) {
+    return -1;
+  }
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left[index];
+    const rightPart = right[index];
+    if (leftPart === void 0) {
+      return -1;
+    }
+    if (rightPart === void 0) {
+      return 1;
+    }
+    const leftNumber = /^\d+$/.test(leftPart) ? Number.parseInt(leftPart, 10) : null;
+    const rightNumber = /^\d+$/.test(rightPart) ? Number.parseInt(rightPart, 10) : null;
+    if (leftNumber !== null && rightNumber !== null) {
+      if (leftNumber !== rightNumber) {
+        return leftNumber > rightNumber ? 1 : -1;
+      }
+      continue;
+    }
+    if (leftNumber !== null) {
+      return -1;
+    }
+    if (rightNumber !== null) {
+      return 1;
+    }
+    if (leftPart !== rightPart) {
+      return leftPart > rightPart ? 1 : -1;
+    }
+  }
+  return 0;
+}
+function compareSemver(left, right) {
+  const parsedLeft = parseSemver(left);
+  const parsedRight = parseSemver(right);
+  if (!parsedLeft || !parsedRight) {
+    return left.localeCompare(right, void 0, { numeric: true });
+  }
+  if (parsedLeft.major !== parsedRight.major) {
+    return parsedLeft.major > parsedRight.major ? 1 : -1;
+  }
+  if (parsedLeft.minor !== parsedRight.minor) {
+    return parsedLeft.minor > parsedRight.minor ? 1 : -1;
+  }
+  if (parsedLeft.patch !== parsedRight.patch) {
+    return parsedLeft.patch > parsedRight.patch ? 1 : -1;
+  }
+  return comparePrerelease(parsedLeft.prerelease, parsedRight.prerelease);
+}
+function getInstallCommand() {
+  return `npm install -g ${PACKAGE_NAME}@latest`;
+}
+async function fetchLatestVersion(env) {
+  const registryUrl = normalizeRegistryUrl(getRegistryUrl(env));
+  const url = `${registryUrl}/${PACKAGE_NAME}/latest`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 2e3);
+  try {
+    const response = await fetch(url, {
+      headers: {
+        accept: "application/json"
+      },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const payload = await response.json();
+    return typeof payload.version === "string" ? payload.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function loadLatestVersionFromState(store) {
+  const state = await store.load();
+  return state.update ?? {};
+}
+async function saveUpdateState(store, update) {
+  const state = await store.load();
+  await store.save({
+    ...state,
+    update
+  });
+}
+async function resolveLatestVersion(env, options) {
+  const store = options?.store ?? new StateStore();
+  const updateState = await loadLatestVersionFromState(store);
+  const lastCheckedAt = readTimestamp(updateState.lastCheckedAt);
+  const now = Date.now();
+  if (!options?.forceRefresh && updateState.latestVersion && lastCheckedAt !== null && now - lastCheckedAt < CACHE_TTL_MS) {
+    return updateState.latestVersion;
+  }
+  const latestVersion = await fetchLatestVersion(env);
+  if (!latestVersion) {
+    return updateState.latestVersion ?? null;
+  }
+  await saveUpdateState(store, {
+    ...updateState,
+    latestVersion,
+    lastCheckedAt: new Date(now).toISOString()
+  });
+  return latestVersion;
+}
+async function getUpdateStatus(currentVersion, env, options) {
+  const resolvedLatestVersion = await resolveLatestVersion(env, {
+    forceRefresh: options?.forceRefresh,
+    store: options?.store
+  });
+  if (!resolvedLatestVersion && options?.forceRefresh) {
+    throw new CliError(
+      `Could not reach the npm registry to check the latest ${PACKAGE_NAME} version.`
+    );
+  }
+  const latestVersion = resolvedLatestVersion ?? currentVersion;
+  return {
+    currentVersion,
+    latestVersion,
+    isOutdated: compareSemver(currentVersion, latestVersion) < 0,
+    installCommand: getInstallCommand()
+  };
+}
+function writeUpdateNotice(status) {
+  writeNoticeBox("Update Available", [
+    `${PACKAGE_NAME} ${status.currentVersion} -> ${status.latestVersion}`,
+    `Run: ${status.installCommand}`
+  ]);
+}
+async function maybeShowUpdateNotice(options) {
+  if (options.env.PEAKURL_DISABLE_UPDATE_CHECK === "1" || options.commandName === "update" || options.options?.json || options.options?.quiet) {
+    return;
+  }
+  if (options.env.PEAKURL_FORCE_UPDATE_NOTICE !== "1" && !process.stderr.isTTY) {
+    return;
+  }
+  const store = new StateStore();
+  const updateState = await loadLatestVersionFromState(store);
+  const status = await getUpdateStatus(options.currentVersion, options.env, {
+    store
+  });
+  if (!status.isOutdated) {
+    return;
+  }
+  const lastNotifiedAt = readTimestamp(updateState.lastNotifiedAt);
+  const alreadyNotifiedForVersion = updateState.lastNotifiedVersion === status.latestVersion;
+  if (alreadyNotifiedForVersion && lastNotifiedAt !== null && Date.now() - lastNotifiedAt < NOTICE_TTL_MS) {
+    return;
+  }
+  await saveUpdateState(store, {
+    ...updateState,
+    lastNotifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastNotifiedVersion: status.latestVersion
+  });
+  writeUpdateNotice(status);
+}
+
+// src/commands/update.ts
+async function updateCommand(options, currentVersion) {
+  const status = await getUpdateStatus(currentVersion, process.env, {
+    forceRefresh: true
+  });
+  const payload = {
+    success: true,
+    message: status.isOutdated ? `A newer PeakURL CLI version is available (${status.latestVersion}).` : `PeakURL CLI ${status.currentVersion} is up to date.`,
+    data: {
+      currentVersion: status.currentVersion,
+      latestVersion: status.latestVersion,
+      isOutdated: status.isOutdated,
+      installCommand: status.installCommand,
+      checkOnly: Boolean(options.check)
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  if (options.json) {
+    writeJson(payload);
+    return;
+  }
+  if (!status.isOutdated) {
+    if (!options.quiet) {
+      writeStdout(`PeakURL CLI ${status.currentVersion} is up to date.`);
+    }
+    return;
+  }
+  if (options.quiet) {
+    writeStdout(status.installCommand);
+    return;
+  }
+  writeNoticeBox(
+    "Update Available",
+    [
+      `peakurl ${status.currentVersion} -> ${status.latestVersion}`,
+      `Run: ${status.installCommand}`
+    ],
+    "stdout"
+  );
+}
+
 // src/commands/whoami.ts
 async function whoamiCommand(options) {
   const config = await resolveStoredConfig(process.env);
@@ -669,7 +996,8 @@ async function readVersion() {
 }
 async function main() {
   const program = new Command();
-  program.name("peakurl").description("PeakURL command-line interface").version(await readVersion()).showHelpAfterError().showSuggestionAfterError().addHelpText(
+  const version = await readVersion();
+  program.name("peakurl").description("PeakURL command-line interface").version(version).showHelpAfterError().showSuggestionAfterError().addHelpText(
     "after",
     `
 Examples:
@@ -677,9 +1005,19 @@ Examples:
   peakurl whoami --json
   peakurl create https://example.com --alias example
   peakurl list --limit 10
+  peakurl update --check
   peakurl get example
   peakurl delete example --quiet`
   ).exitOverride();
+  program.hook("preAction", async (_command, actionCommand) => {
+    const options = actionCommand.optsWithGlobals();
+    await maybeShowUpdateNotice({
+      currentVersion: version,
+      commandName: actionCommand.name(),
+      options,
+      env: process.env
+    });
+  });
   program.command("login").description(
     "Save PeakURL credentials after verifying them with GET /users/me."
   ).option(
@@ -694,6 +1032,12 @@ Examples:
   program.command("list").description("List PeakURL short links.").option("--page <number>", "Page number", parsePositiveInteger("page")).option("--limit <number>", "Page size", parsePositiveInteger("limit")).option("--search <query>", "Search term").option("--sort-by <field>", "Sort field").option("--sort-order <order>", "Sort order, for example asc or desc").option("--json", "Print machine-readable output").option("--quiet", "Print a minimal per-link value").action(listCommand);
   program.command("get").description("Fetch a single PeakURL short link by id or alias.").argument("<id-or-alias>", "Link identifier or alias").option("--json", "Print machine-readable output").option("--quiet", "Print only the short URL").action(getCommand);
   program.command("delete").description("Delete a PeakURL short link by id or alias.").argument("<id-or-alias>", "Link identifier or alias").option("--json", "Print machine-readable output").option("--quiet", "Suppress success output").action(deleteCommand);
+  program.command("update").description(
+    "Check for a newer CLI version and print the npm command to install it."
+  ).option(
+    "--check",
+    "Alias for checking update status without changing anything"
+  ).option("--json", "Print machine-readable output").option("--quiet", "Print minimal output").action((options) => updateCommand(options, version));
   try {
     await program.parseAsync(process.argv);
   } catch (error) {

package/package.json

@@ -1,11 +1,25 @@
 {
     "name": "peakurl",
-    "version": "0.0.3",
-    "description": "PeakURL command-line interface",
+    "version": "0.1.1",
+    "description": "Official CLI for creating, listing, and managing PeakURL short links from the terminal",
+    "homepage": "https://peakurl.org",
+    "bugs": {
+        "url": "https://github.com/PeakURL/PeakURL-CLI/issues"
+    },
     "repository": {
         "type": "git",
-        "url": "https://github.com/PeakURL/PeakURL-CLI.git"
+        "url": "git+https://github.com/PeakURL/PeakURL-CLI.git"
     },
+    "keywords": [
+        "peakurl",
+        "url shortener",
+        "short links",
+        "link shortening",
+        "cli",
+        "command line",
+        "terminal",
+        "productivity"
+    ],
     "type": "module",
     "bin": {
         "peakurl": "bin/peakurl.js"
@@ -21,7 +35,7 @@
         "dev": "tsx src/index.ts",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "test": "tsx --test test/*.test.ts",
+        "test": "npm run build && tsx --test test/*.test.ts",
         "typecheck": "tsc --noEmit",
         "prepare": "npm run build"
     },