bs58ify 0.0.0 → 0.1.0

package/docs/superpowers/plans/2026-06-22-bs58ify-success-messages.md

@@ -0,0 +1,74 @@
+# bs58ify Success Messages Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Print a confirmation after each successful `bs58ify` conversion writes its output file.
+
+**Architecture:** Keep the existing conversion and write operations unchanged. Each Commander action writes an exact stdout message only after `writeFile` resolves, and process-level CLI tests capture the built binary’s output.
+
+**Tech Stack:** TypeScript, Commander, Node.js `fs/promises`, Bun test runner.
+
+---
+
+### Task 1: Verify and emit command success messages
+
+**Files:**
+- Modify: `tests/cli.test.ts`
+- Modify: `src/cli.ts`
+
+- [ ] **Step 1: Write failing built-CLI output tests**
+
+```ts
+test('reports successful encode output', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'bs58ify-'));
+  const output = join(directory, 'encoded.txt');
+  const result = await Bun.$`node dist/cli.js encode '[1,2,3,4]' ${output}`.quiet();
+
+  expect(result.stdout.toString()).toBe(`Encoded Base58 value written to ${output}\n`);
+});
+
+test('reports successful decode output', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'bs58ify-'));
+  const output = join(directory, 'decoded.json');
+  const result = await Bun.$`node dist/cli.js decode 2VfUX ${output}`.quiet();
+
+  expect(result.stdout.toString()).toBe(`Decoded JSON byte array written to ${output}\n`);
+});
+```
+
+- [ ] **Step 2: Verify the new tests fail**
+
+Run: `bun test tests/cli.test.ts`
+
+Expected: FAIL because the built commands write no standard-output confirmation.
+
+- [ ] **Step 3: Add output after successful writes**
+
+```ts
+await writeFile(outputPath, encodeByteArray(input));
+console.log(`Encoded Base58 value written to ${outputPath}`);
+```
+
+```ts
+await writeFile(outputPath, decodeBase58(input));
+console.log(`Decoded JSON byte array written to ${outputPath}`);
+```
+
+- [ ] **Step 4: Verify the focused CLI suite passes**
+
+Run: `bun test tests/cli.test.ts`
+
+Expected: PASS, including the exact encode and decode confirmation messages.
+
+- [ ] **Step 5: Verify the full project**
+
+Run: `bun test && bun run typecheck && bun run build`
+
+Expected: all commands exit 0.
+
+- [ ] **Step 6: Commit the implementation**
+
+```bash
+git add src/cli.ts tests/cli.test.ts
+git commit -m "feat: report successful CLI conversions"
+```

package/docs/superpowers/specs/2026-06-22-bs58ify-cli-design.md

@@ -0,0 +1,37 @@
+# bs58ify CLI Design
+
+## Goal
+
+Replace the two positional-argument scripts with a distributable Commander CLI named `bs58ify`. The package will be published under the existing user-owned `bs58ify` npm package.
+
+## CLI contract
+
+The compiled executable exposes two required subcommands:
+
+```sh
+bs58ify encode <uint8array-json> <output-filepath>
+bs58ify decode <base58-private-key> <output-filepath>
+```
+
+- `encode` parses a JSON array of byte values, Base58-encodes it, and writes the resulting text to `output-filepath`.
+- `decode` Base58-decodes its input, serializes the bytes as a JSON array, and writes it to `output-filepath`.
+- Commander owns command parsing, help output, required arguments, and non-zero failure behavior for invalid invocations.
+- Invalid JSON or Base58 input must cause a non-zero command failure without reporting success.
+
+## Architecture
+
+Conversion logic moves into a small reusable module containing pure encode/decode functions. A CLI entry module owns only Commander configuration, conversion invocation, and file writes. This permits unit tests to exercise conversion semantics without spawning a process, while command tests validate the public CLI behavior.
+
+The current root-level `bs58.ts` and `uint8array.ts` scripts are replaced by the unified CLI entry point and supporting module under `src/`.
+
+## Packaging and build
+
+- Set the package name to `bs58ify`.
+- Add `commander` as a runtime dependency and `rolldown` as a development dependency.
+- Add a `build` script that bundles the CLI to `dist/cli.js` for Node.js, preserving a `#!/usr/bin/env node` shebang.
+- Add a `bin` mapping from `bs58ify` to `dist/cli.js`.
+- Keep Bun as the package manager and test runner.
+
+## Documentation and verification
+
+The README will document installation, building locally, and both subcommands. Tests cover valid encode/decode conversions, malformed conversion inputs, CLI help, successful file output, and failure exit status. Verification runs the Bun test suite, TypeScript type checking, the Rolldown build, and the built `dist/cli.js` executable.

package/docs/superpowers/specs/2026-06-22-bs58ify-success-messages-design.md

@@ -0,0 +1,16 @@
+# bs58ify Success Messages Design
+
+## Goal
+
+Provide clear confirmation after each successful file conversion without exposing converted values in terminal output.
+
+## Behavior
+
+- After `encode` finishes writing its output file, it writes `Encoded Base58 value written to <output>` to standard output.
+- After `decode` finishes writing its output file, it writes `Decoded JSON byte array written to <output>` to standard output.
+- A message is emitted only after `writeFile` resolves successfully.
+- Failed conversions or file writes retain their existing non-zero failure behavior and emit no success message.
+
+## Verification
+
+CLI tests will capture standard output for each successful subcommand and assert the exact message. Existing error-path and built-binary tests remain in place.

package/oxfmt.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "oxfmt";
+
+export default defineConfig({
+  useTabs: false,
+  semi: true,
+  singleQuote: false,
+  trailingComma: "all",
+  sortImports: true,
+  sortTailwindcss: true,
+  sortPackageJson: false,
+});

package/oxlint.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  plugins: ["typescript", "unicorn", "oxc", "import"],
+  categories: {
+    correctness: "error",
+  },
+  rules: {},
+  env: {
+    builtin: true,
+  },
+});

package/package.json

@@ -1,11 +1,42 @@
 {
   "name": "bs58ify",
-  "version": "0.0.0",
-  "description": "Placeholder for bs58ify",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": [],
-  "author": "chiiyuen (https://www.npmjs.com/~chiiyuen)",
-  "license": "UNLICENSED",
-  "private": false
-}
+  "version": "0.1.0",
+  "description": "A CLI for converting between Base58 strings and JSON byte arrays.",
+  "type": "module",
+  "bin": {
+    "bs58ify": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "rolldown src/cli.ts --config rolldown.config.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt --check",
+    "fmt:fix": "oxfmt --write",
+    "publish:npm": "bun publish --registry https://registry.npmjs.org/",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "bs58": "^6.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.8",
+    "oxfmt": "^0.55.0",
+    "oxlint": "^1.70.0",
+    "rolldown": "^1.1.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "keywords": [
+    "bs58",
+    "base58",
+    "cli",
+    "command-line",
+    "utility"
+  ]
+}

package/rolldown.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "rolldown";
+
+export default defineConfig({
+  input: "src/cli.ts",
+  platform: "node",
+  output: {
+    file: "dist/cli.js",
+    format: "esm",
+    banner: "#!/usr/bin/env node",
+  },
+});

package/src/cli.ts

@@ -0,0 +1,46 @@
+import { writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import { Command } from "commander";
+
+import { decodeBase58, encodeByteArray } from "./conversion";
+
+export function createProgram(): Command {
+  const program = new Command()
+    .name("bs58ify")
+    .description("Encode and decode Base58 byte arrays.");
+
+  return program
+    .action(() => {
+      program.outputHelp();
+    })
+    .addCommand(
+      new Command("encode")
+        .description("Encode a JSON byte array as Base58.")
+        .argument("<uint8array>", "JSON array of bytes")
+        .argument("<output>", "file to write the Base58 result to")
+        .action(async (input: string, outputPath: string) => {
+          await writeFile(outputPath, encodeByteArray(input));
+          console.log(`Encoded Base58 value written to ${outputPath}`);
+        }),
+    )
+    .addCommand(
+      new Command("decode")
+        .description("Decode Base58 as a JSON byte array.")
+        .argument("<base58>", "Base58-encoded value")
+        .argument("<output>", "file to write the JSON result to")
+        .action(async (input: string, outputPath: string) => {
+          await writeFile(outputPath, decodeBase58(input));
+          console.log(`Decoded JSON byte array written to ${outputPath}`);
+        }),
+    );
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  createProgram()
+    .parseAsync()
+    .catch((error: unknown) => {
+      console.error(error instanceof Error ? error.message : error);
+      process.exitCode = 1;
+    });
+}

package/src/conversion.ts

@@ -0,0 +1,18 @@
+import bs58 from "bs58";
+
+export function encodeByteArray(input: string): string {
+  const values: unknown = JSON.parse(input);
+
+  if (
+    !Array.isArray(values) ||
+    values.some((value) => !Number.isInteger(value) || value < 0 || value > 255)
+  ) {
+    throw new Error("Input must be a JSON array of bytes.");
+  }
+
+  return bs58.encode(new Uint8Array(values));
+}
+
+export function decodeBase58(input: string): string {
+  return JSON.stringify(Array.from(bs58.decode(input)));
+}

package/tests/cli.test.ts

@@ -0,0 +1,64 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createProgram } from "../src/cli";
+
+test("registers encode and decode commands", () => {
+  expect(createProgram().commands.map((command) => command.name())).toEqual(["encode", "decode"]);
+});
+
+test("writes encoded output", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bs58ify-"));
+  const output = join(directory, "encoded.txt");
+
+  await createProgram().parseAsync(["node", "bs58ify", "encode", "[1,2,3,4]", output]);
+
+  expect(await readFile(output, "utf8")).toBe("2VfUX");
+});
+
+test("rejects malformed command input", async () => {
+  await expect(
+    createProgram().parseAsync(["node", "bs58ify", "encode", "not-json", "out.txt"]),
+  ).rejects.toThrow();
+});
+
+test("reports successful encode output", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bs58ify-"));
+  const output = join(directory, "encoded.txt");
+  await Bun.$`bun run build`.quiet();
+
+  const result = await Bun.$`node dist/cli.js encode '[1,2,3,4]' ${output}`.quiet();
+
+  expect(result.stdout.toString()).toBe(`Encoded Base58 value written to ${output}\n`);
+});
+
+test("reports successful decode output", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "bs58ify-"));
+  const output = join(directory, "decoded.json");
+  await Bun.$`bun run build`.quiet();
+
+  const result = await Bun.$`node dist/cli.js decode 2VfUX ${output}`.quiet();
+
+  expect(result.stdout.toString()).toBe(`Decoded JSON byte array written to ${output}\n`);
+});
+
+test("builds a CLI with a Node shebang", async () => {
+  const packageJson = await Bun.file("package.json").json();
+  expect(packageJson.scripts.build).toBe("rolldown src/cli.ts --config rolldown.config.ts");
+  expect(await Bun.file("rolldown.config.ts").exists()).toBe(true);
+
+  const result = await Bun.$`bun run build`.quiet().nothrow();
+
+  expect(result.exitCode).toBe(0);
+  expect((await Bun.file("dist/cli.js").text()).startsWith("#!/usr/bin/env node")).toBe(true);
+
+  const help = await Bun.$`node dist/cli.js --help`.quiet();
+  expect(help.stdout.toString()).toContain("encode");
+  expect(help.stdout.toString()).toContain("decode");
+
+  const noArguments = await Bun.$`node dist/cli.js`.quiet().nothrow();
+  expect(noArguments.exitCode).toBe(0);
+  expect(noArguments.stdout.toString()).toContain("Usage: bs58ify");
+});

package/tests/conversion.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+
+import { decodeBase58, encodeByteArray } from "../src/conversion";
+
+test("encodes a JSON byte array as Base58", () => {
+  expect(encodeByteArray("[1,2,3,4]")).toBe("2VfUX");
+});
+
+test("decodes Base58 into a JSON byte array", () => {
+  expect(decodeBase58("2VfUX")).toBe("[1,2,3,4]");
+});
+
+test("rejects a JSON array containing an invalid byte", () => {
+  expect(() => encodeByteArray("[256]")).toThrow("Input must be a JSON array of bytes.");
+});

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["esnext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/index.js

@@ -1 +0,0 @@
-// Placeholder