@simplysm/sd-claude 13.0.72 → 13.0.74

package/README.md

@@ -1,24 +1,297 @@
 # @simplysm/sd-claude
 
-Simplysm Claude Code CLI — asset installer
+Simplysm Claude Code CLI — asset installer and Claude account profile manager.
 
 ## Installation
 
+```bash
 pnpm add @simplysm/sd-claude
+```
 
-## Source Index
+On install, the `postinstall` script automatically copies Claude Code assets (`sd-*` entries) from the package's `claude/` directory into the project's `.claude/` directory and configures the status line in `.claude/settings.json`.
 
-### Commands
+## CLI
 
-| Source | Exports | Description | Test |
-|--------|---------|-------------|------|
-| `src/commands/install.ts` | `runInstall` | Copies sd-* Claude Code assets into the project's `.claude/` directory | `-` |
-| `src/commands/auth-utils.ts` | `validateName`, `getProfileDir`, `profileExists`, `listProfiles`, `readCurrentAuth`, `readCurrentCredentials`, `getCurrentUserID` | Shared helpers for reading and locating Claude auth profile data | `auth-utils.spec.ts` |
-| `src/commands/auth-add.ts` | `runAuthAdd` | Saves the current Claude login session as a named auth profile | `auth-add.spec.ts` |
-| `src/commands/auth-use.ts` | `runAuthUse` | Switches the active Claude login to a saved named profile | `auth-use.spec.ts` |
-| `src/commands/auth-list.ts` | `runAuthList` | Lists all saved auth profiles with email and token expiry info | `auth-list.spec.ts` |
-| `src/commands/auth-remove.ts` | `runAuthRemove` | Deletes a saved auth profile from the local profile store | `auth-remove.spec.ts` |
+The package provides the `sd-claude` binary.
 
-## License
+```
+sd-claude <command> [options]
+sd-claude --help
+```
 
-Apache-2.0
+### `install`
+
+Installs Claude Code assets to the project's `.claude/` directory. This is also run automatically via the `postinstall` script.
+
+```bash
+sd-claude install
+```
+
+**Behavior:**
+
+- Locates the project root via `INIT_CWD` environment variable or by finding `node_modules` in the path.
+- Copies all `sd-*` entries from the package's `claude/` directory to the project's `.claude/` directory.
+- Removes any previously installed `sd-*` entries before copying (clean install).
+- Adds a `statusLine` entry to `.claude/settings.json` if one is not already configured:
+  ```json
+  { "type": "command", "command": "node .claude/sd-statusline.js" }
+  ```
+- Skips installation when running inside the simplysm monorepo at the same major version.
+- Errors during installation are suppressed (logged as warnings) to avoid blocking `pnpm install`.
+
+### `auth`
+
+Manages Claude account profiles. Profiles are stored in `~/.sd-claude/auth/<name>/`.
+
+Each profile stores:
+- `auth.json` — `oauthAccount` and `userID` from `~/.claude.json`
+- `credentials.json` — full contents of `~/.claude/.credentials.json`
+
+#### `auth add <name>`
+
+Saves the currently logged-in Claude account as a named profile.
+
+```bash
+sd-claude auth add <name>
+```
+
+- `<name>`: Profile name. Must match `[a-z0-9_-]+`.
+- Reads the current auth state from `~/.claude.json` and `~/.claude/.credentials.json`.
+- Fails if the profile name already exists. Remove it first with `auth remove`.
+- Requires an active Claude login. Run `/login` in Claude Code before saving.
+
+**Example:**
+
+```bash
+sd-claude auth add personal
+sd-claude auth add work
+```
+
+#### `auth use <name>`
+
+Switches to a saved Claude account profile.
+
+```bash
+sd-claude auth use <name>
+```
+
+- Reads the saved `auth.json` and `credentials.json` from `~/.sd-claude/auth/<name>/`.
+- Updates `~/.claude.json` (only `oauthAccount` and `userID` fields; other fields are preserved).
+- Replaces `~/.claude/.credentials.json` entirely with the saved credentials.
+- Warns if the saved token has expired (run `/login` after switching to refresh).
+
+**Example:**
+
+```bash
+sd-claude auth use work
+```
+
+#### `auth list`
+
+Displays all saved profiles with their active status, email, token expiry, and usage.
+
+```bash
+sd-claude auth list
+```
+
+Output format per profile:
+
+```
+* <name> (<email>) expires: YYYY-MM-DD │ 5h: <pct>(<remaining>) │ 7d: <pct>(<remaining>)
+```
+
+- `*` marks the currently active profile (matched by `userID`); inactive profiles show a space.
+- Usage is fetched live from `https://api.anthropic.com/api/oauth/usage` using the profile's OAuth token (5-second timeout). Shows `?` when unavailable or when the token is expired.
+- Usage shows the `daily` window (falling back to `five_hour`) as the `5h` column, and `seven_day` as the `7d` column.
+- Profiles are sorted alphabetically.
+
+**Example output:**
+
+```
+* work (work@company.com) expires: 2025-12-31 │ 5h: 42%(3h15m) │ 7d: 18%(2d4h)
+  personal (personal@gmail.com) expires: 2025-11-01 │ 5h: ? │ 7d: ?
+```
+
+#### `auth remove <name>`
+
+Removes a saved Claude account profile.
+
+```bash
+sd-claude auth remove <name>
+```
+
+- Deletes `~/.sd-claude/auth/<name>/` and all its contents.
+- Warns if the profile being removed is the currently active account (the active session in Claude Code is not affected).
+
+**Example:**
+
+```bash
+sd-claude auth remove personal
+```
+
+## Programmatic API
+
+All commands are also exported as functions for use in Node.js scripts.
+
+```ts
+import {
+  runInstall,
+  runAuthAdd,
+  runAuthUse,
+  runAuthList,
+  runAuthRemove,
+  validateName,
+  getProfileDir,
+  profileExists,
+  listProfiles,
+  readCurrentAuth,
+  readCurrentCredentials,
+  getCurrentUserID,
+} from "@simplysm/sd-claude";
+```
+
+### `runInstall(): void`
+
+Runs the install command programmatically. See [`install`](#install) for behavior details.
+
+```ts
+import { runInstall } from "@simplysm/sd-claude";
+
+runInstall();
+```
+
+### `runAuthAdd(name: string, homeDir?: string): void`
+
+Saves the currently logged-in Claude account as a named profile.
+
+- `name`: Profile name (validated against `[a-z0-9_-]+`).
+- `homeDir`: Override for the home directory (defaults to `os.homedir()`). Primarily used in tests.
+
+```ts
+import { runAuthAdd } from "@simplysm/sd-claude";
+
+runAuthAdd("work");
+```
+
+### `runAuthUse(name: string, homeDir?: string): void`
+
+Switches to a saved Claude account profile.
+
+- `name`: Profile name to switch to.
+- `homeDir`: Override for the home directory.
+
+```ts
+import { runAuthUse } from "@simplysm/sd-claude";
+
+runAuthUse("work");
+```
+
+### `runAuthList(homeDir?: string): Promise<void>`
+
+Prints all saved profiles to stdout with status, expiry, and live usage data.
+
+- `homeDir`: Override for the home directory.
+
+```ts
+import { runAuthList } from "@simplysm/sd-claude";
+
+await runAuthList();
+```
+
+### `runAuthRemove(name: string, homeDir?: string): void`
+
+Removes a saved Claude account profile.
+
+- `name`: Profile name to remove.
+- `homeDir`: Override for the home directory.
+
+```ts
+import { runAuthRemove } from "@simplysm/sd-claude";
+
+runAuthRemove("personal");
+```
+
+### `validateName(name: string): void`
+
+Validates that a profile name matches `[a-z0-9_-]+`. Throws an `Error` if invalid.
+
+```ts
+import { validateName } from "@simplysm/sd-claude";
+
+validateName("my-profile"); // OK
+validateName("My Profile"); // throws Error
+```
+
+### `getProfileDir(name: string, homeDir?: string): string`
+
+Returns the absolute path to the profile directory: `<homeDir>/.sd-claude/auth/<name>`.
+
+```ts
+import { getProfileDir } from "@simplysm/sd-claude";
+
+const dir = getProfileDir("work");
+// e.g. "/home/user/.sd-claude/auth/work"
+```
+
+### `profileExists(name: string, homeDir?: string): boolean`
+
+Returns `true` if the profile directory exists.
+
+```ts
+import { profileExists } from "@simplysm/sd-claude";
+
+if (profileExists("work")) {
+  console.log("Profile work exists");
+}
+```
+
+### `listProfiles(homeDir?: string): string[]`
+
+Returns an array of all saved profile names (directory names under `~/.sd-claude/auth/`). Returns an empty array if no profiles exist.
+
+```ts
+import { listProfiles } from "@simplysm/sd-claude";
+
+const profiles = listProfiles();
+// e.g. ["personal", "work"]
+```
+
+### `readCurrentAuth(homeDir?: string): { oauthAccount: Record<string, unknown>; userID: string }`
+
+Reads `oauthAccount` and `userID` from `~/.claude.json`. Throws if not logged in.
+
+```ts
+import { readCurrentAuth } from "@simplysm/sd-claude";
+
+const { oauthAccount, userID } = readCurrentAuth();
+```
+
+### `readCurrentCredentials(homeDir?: string): Record<string, unknown>`
+
+Reads and returns the full contents of `~/.claude/.credentials.json`.
+
+```ts
+import { readCurrentCredentials } from "@simplysm/sd-claude";
+
+const credentials = readCurrentCredentials();
+```
+
+### `getCurrentUserID(homeDir?: string): string | undefined`
+
+Returns the `userID` from `~/.claude.json`, or `undefined` if the file does not exist or cannot be read.
+
+```ts
+import { getCurrentUserID } from "@simplysm/sd-claude";
+
+const userID = getCurrentUserID();
+```
+
+## Profile Storage Layout
+
+```
+~/.sd-claude/
+  auth/
+    <name>/
+      auth.json         # { oauthAccount, userID }
+      credentials.json  # full ~/.claude/.credentials.json snapshot
+```

package/claude/refs/sd-code-conventions.md

@@ -39,8 +39,19 @@ async function readFileAsync() { ... } // Async suffix prohibited
 - Not enforced — omit when code is self-explanatory
 - When written, use Korean
 
+## Re-export Restriction
+
+- Re-export (`export * from`, `export { } from`) is **only allowed in `src/index.ts`**
+- All other files must not re-export — duplicated re-exports make code harder to find and maintain
+
 ## index.ts Export Pattern
 
 - Large packages: `#region`/`#endregion` for sections + `//` for sub-groups
 - Small packages (≤10 exports): `//` comments only
 - Always `export *` (wildcard), never explicit `export type { ... } from "..."`
+
+## Type Safety for Public APIs
+
+- API changes must be detectable via **typecheck alone** — all affected usage sites must show compile errors
+- Public component props must support **IDE intellisense** (autocomplete, type hints)
+- Avoid `any` in public-facing types; use generics or specific union types instead

package/claude/rules/sd-claude-rules.md

@@ -32,7 +32,18 @@ If a referenced file or document cannot be found, **stop immediately and ask the
 - Do NOT add features, refactoring, improvements, or documentation beyond the requested scope.
 - When in doubt, **ask first** before proceeding.
 - Responses like "I'll create it myself" or "I'll add that as well" are strictly prohibited.
+- **Do NOT comment on code outside the requested change.** This includes:
+  - Listing issues you noticed but did not fix
+  - Describing what you "left alone" or "did not change"
+  - "참고", "suggestions", "by the way", "note", "what I left alone"
+  - Any unsolicited observations about surrounding code quality
+  - Only describe **what you changed** — nothing else
 
-## ⚠️ CRITICAL — NEVER SKIP
+## Asking Clarifying Questions
 
-**Before EVERY `AskUserQuestion` call, output `---` as the last line.** The widget clips text above it. No exceptions.
+When you need to ask the user a question, you MUST use the `AskUserQuestion` tool. Do NOT ask questions in plain text.
+
+- **Wrong:** Writing questions as text in your response
+- **Right:** Calling the `AskUserQuestion` tool
+
+**Before EVERY `AskUserQuestion` call, output `---` as the last line.** The widget clips text above it. No exceptions.

package/claude/skills/sd-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sd-brainstorm
-description: "Design exploration before implementation (explicit invocation only)"
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
 ---
 
 # Brainstorming Ideas Into Designs

package/claude/skills/sd-check/SKILL.md

@@ -1,17 +1,26 @@
 ---
 name: sd-check
 description: "Typecheck, lint, test verification (explicit invocation only)"
-allowed-tools: Bash(npm run check), Bash(npm run typecheck), Bash(npm run lint --fix), Bash(npm run vitest)
+allowed-tools: Bash(npm run check:*), Bash(pnpm run check:*), Bash(yarn run check:*), Bash(npm run typecheck:*), Bash(pnpm run typecheck:*), Bash(yarn run typecheck:*), Bash(npm run lint:*), Bash(pnpm run lint:*), Bash(yarn run lint:*), Bash(npm run vitest:*), Bash(pnpm run vitest:*), Bash(yarn run vitest:*)
 ---
 
 # sd-check
 
-Run `npm run check`, fix errors, repeat until clean.
+Run `$PM run check`, fix errors, repeat until clean.
+
+## Package Manager Detection
+
+Before running any commands, detect the package manager:
+- If `pnpm-lock.yaml` exists in project root → use `pnpm`
+- If `yarn.lock` exists in project root → use `yarn`
+- Otherwise → use `npm`
+
+`$PM` in all commands below refers to the detected package manager.
 
 ## Usage
 
 ```
-npm run check [path] [--type typecheck|lint|test]
+$PM run check [path] [--type typecheck|lint|test]
 ```
 
 | Example                               | Effect                    |
@@ -25,11 +34,11 @@ Multiple types: `--type typecheck,lint`. No path = full project. No type = all c
 
 ## Workflow
 
-1. **Run** `npm run check [path] [--type type]` (timeout: 600000)
+1. **Run** `$PM run check [path] [--type type]` (timeout: 600000)
 2. **All passed?** Report with actual output numbers → done
 3. **Errors?** Fix in priority order: typecheck → lint → test (fixes cascade)
-   - Test failures: run `git diff` to decide — update test or fix source
-   - **E2E test failures** (browser/solid/service project): use Playwright MCP to investigate before fixing
+   - Test failures: **MUST** run `git log` to decide — update test or fix source
+   - **E2E test failures**: use Playwright MCP to investigate before fixing
      1. `browser_navigate` to the target URL
      2. `browser_snapshot` / `browser_take_screenshot` (save to `.tmp/playwright/`) to see page state
      3. `browser_console_messages` for JS errors

package/claude/skills/sd-commit/SKILL.md

@@ -58,6 +58,8 @@ Examples:
 - `fix(orm-node): handle null values in bulk insert`
 - `docs: update README with new API examples`
 
+> **Note:** The examples above are in English for reference only. The actual description MUST be written in the system's configured language.
+
 Use a HEREDOC for multi-line messages when needed.
 
 ## Execution

package/claude/skills/sd-debug/find-polluter.sh

@@ -14,6 +14,12 @@ fi
 CHECK_PATH="$1"
 TEST_PATTERN="$2"
 
+# Detect package manager: pnpm -> yarn -> npm (default)
+if [ -f "pnpm-lock.yaml" ]; then PM="pnpm"
+elif [ -f "yarn.lock" ]; then PM="yarn"
+else PM="npm"
+fi
+
 # Find all test files matching pattern
 readarray -t TEST_FILES < <(find . -path "$TEST_PATTERN" -type f)
 
@@ -37,7 +43,7 @@ for test_file in "${TEST_FILES[@]}"; do
     echo "Testing: $test_file"
 
     # Run the test
-    npm test "$test_file" > /dev/null 2>&1 || true
+    $PM test "$test_file" > /dev/null 2>&1 || true
 
     # Check if pollution appeared
     if [ -e "$CHECK_PATH" ]; then
@@ -48,7 +54,7 @@ for test_file in "${TEST_FILES[@]}"; do
         ls -la "$CHECK_PATH" 2>/dev/null || echo "(path exists but can't stat)"
         echo ""
         echo "Investigate with:"
-        echo "  npm test '$test_file' -- --reporter=verbose"
+        echo "  $PM test '$test_file' -- --reporter=verbose"
         echo "  git diff"
         exit 0
     fi

package/claude/skills/sd-debug/root-cause-tracing.md

@@ -93,10 +93,10 @@ async function gitInit(directory: string) {
 
 **Critical:** Use `console.error()` in tests (not logger - may not show)
 
-**Run and capture:**
+**Run and capture** (detect PM: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise → npm):
 
 ```bash
-npm test 2>&1 | grep 'DEBUG git init'
+$PM test 2>&1 | grep 'DEBUG git init'
 ```
 
 **Analyze stack traces:**

package/claude/skills/sd-plan/SKILL.md

@@ -49,6 +49,15 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 ---
 ```
 
+## Package Manager Detection
+
+When writing run commands in the plan, detect the package manager:
+- If `pnpm-lock.yaml` exists in project root → use `pnpm`
+- If `yarn.lock` exists in project root → use `yarn`
+- Otherwise → use `npm`
+
+`$PM` in the task template below refers to the detected package manager.
+
 ## Task Structure
 
 ```markdown
@@ -70,7 +79,7 @@ test("specific behavior", () => {
 
 **Step 2: Run test to verify it fails**
 
-Run: `pnpm vitest exact/path/to/tests/file.spec.ts --run`
+Run: `$PM run vitest exact/path/to/tests/file.spec.ts --run`
 Expected: FAIL with "functionUnderTest is not defined"
 
 **Step 3: Write minimal implementation**
@@ -83,7 +92,7 @@ function functionUnderTest(input: InputType): OutputType {
 
 **Step 4: Run test to verify it passes**
 
-Run: `pnpm vitest exact/path/to/tests/file.spec.ts --run`
+Run: `$PM run vitest exact/path/to/tests/file.spec.ts --run`
 Expected: PASS
 
 **Step 5: Commit**

package/claude/skills/sd-plan-dev/SKILL.md

@@ -221,11 +221,13 @@ Done!
 
 ## Batch Integration Check
 
-Between batches, run targeted verification on affected packages before starting the next batch:
+Between batches, run targeted verification on affected packages before starting the next batch.
+
+Detect the package manager first (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise → npm):
 
 ```bash
-npm run typecheck [affected packages]
-npm run lint [affected packages]
+$PM run typecheck [affected packages]
+$PM run lint [affected packages]
 ```
 
 This catches cross-task integration issues early — especially when the next batch depends on the current batch's output. Do NOT skip this even if individual task reviews passed.

package/claude/skills/sd-plan-dev/final-review-prompt.md

@@ -37,9 +37,9 @@ Individual tasks already passed spec and quality reviews. Focus on cross-task in
 
 ### Verification
 
-Run and report results:
-- `npm run typecheck [affected packages]`
-- `npm run lint [affected packages]`
+Detect the package manager (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise → npm), then run and report results:
+- `$PM run typecheck [affected packages]`
+- `$PM run lint [affected packages]`
 
 ### Report