@simplysm/sd-claude 13.0.78 → 13.0.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-claude",
-  "version": "13.0.78",
+  "version": "13.0.81",
   "description": "Simplysm Claude Code CLI — asset installer",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -17,7 +17,8 @@
     "src",
     "tests",
     "scripts",
-    "claude"
+    "claude",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {

package/src/commands/install.ts

@@ -39,7 +39,7 @@ export function runInstall(): void {
 
     cleanSdEntries(targetDir);
     copySdEntries(sourceDir, targetDir, sourceEntries);
-    setupStatusLine(targetDir);
+    setupSettings(targetDir);
 
     // eslint-disable-next-line no-console
     console.log(`[@simplysm/sd-claude] Installed ${sourceEntries.length} sd-* entries.`);
@@ -144,18 +144,40 @@ function copySdEntries(sourceDir: string, targetDir: string, entries: string[]):
   }
 }
 
-/** Adds statusLine configuration to settings.json. */
-function setupStatusLine(targetDir: string): void {
+/** Ensures statusLine and SessionStart hooks are configured in settings.json. */
+function setupSettings(targetDir: string): void {
   const settingsPath = path.join(targetDir, "settings.json");
-  const sdStatusLineCommand = "node .claude/sd-statusline.js";
 
   let settings: Record<string, unknown> = {};
   if (fs.existsSync(settingsPath)) {
     settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8")) as Record<string, unknown>;
   }
 
-  if (settings["statusLine"] == null) {
-    settings["statusLine"] = { type: "command", command: sdStatusLineCommand };
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  // statusLine: always overwrite
+  settings["statusLine"] = { type: "command", command: "python .claude/sd-statusline.py" };
+
+  // SessionStart: ensure sd-session-start hook exists with correct config
+  const sdSessionEntry = {
+    matcher: "startup|resume|clear|compact",
+    hooks: [{ type: "command", command: "bash .claude/sd-session-start.sh" }],
+  };
+
+  const sessionStart = settings["SessionStart"] as
+    | Array<{ matcher?: string; hooks?: Array<{ type: string; command: string }> }>
+    | undefined;
+
+  if (sessionStart == null) {
+    settings["SessionStart"] = [sdSessionEntry];
+  } else {
+    const idx = sessionStart.findIndex((entry) =>
+      entry.hooks?.some((hook) => hook.command.includes("sd-session-start")),
+    );
+    if (idx >= 0) {
+      sessionStart[idx] = sdSessionEntry;
+    } else {
+      sessionStart.push(sdSessionEntry);
+    }
   }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }

package/README.md

@@ -1,297 +0,0 @@
-# @simplysm/sd-claude
-
-Simplysm Claude Code CLI — asset installer and Claude account profile manager.
-
-## Installation
-
-```bash
-pnpm add @simplysm/sd-claude
-```
-
-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`.
-
-## CLI
-
-The package provides the `sd-claude` binary.
-
-```
-sd-claude <command> [options]
-sd-claude --help
-```
-
-### `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-angular.md

@@ -1,127 +0,0 @@
-# Angular Guidelines (v12 only)
-
-> v13 has no Angular (replaced by SolidJS). Rules below are v12 only.
-
-## Core Rules
-
-- **Signal-based**: Do not use RxJS for state. Use `$signal`, `$computed`, `$effect`
-- **Standalone only**: All components must have `standalone: true`
-- **OnPush + None**: `ChangeDetectionStrategy.OnPush` and `ViewEncapsulation.None` are mandatory
-- **input()/output()**: Do not use `@Input()`, `@Output()` decorators → use `input()`, `output()`, `model()` instead
-- **Control flow**: Use `@if`, `@for`, `@switch` (no `*ngIf`, `*ngFor`)
-- **DI**: Use `inject()` (no constructor parameter injection)
-- **Icons**: Use `@ng-icons/tabler-icons` (not FontAwesome)
-- **Package imports**: Import `@simplysm/sd-angular` only from root (no subfolders)
-
-## Signal Utilities
-
-- `$signal<T>(value?)` — writable signal (can mark dirty with `$mark()`)
-- `$computed(fn)` — synchronous computed. Async: `$computed([deps], asyncFn, { initialValue })`
-- `$effect(fn)` — dependency tracking: `$effect([() => dep1()], () => { ... })`
-- `$arr(signal)` — array operations (`.insert()`, `.remove()`, `.toggle()`, `.diffs()`)
-- `$obj(signal)` — object operations (`.updateField()`, `.snapshot()`, `.changed()`)
-- `$set(signal)` — Set operations (`.add()`, `.toggle()`)
-
-## Component Pattern
-
-```typescript
-@Component({
-  selector: "app-my-page",
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  encapsulation: ViewEncapsulation.None,
-  standalone: true,
-  imports: [SdTextfieldControl, SdButtonControl],
-  template: `
-    ...
-  `,
-})
-export class MyPage {
-  #sdToast = inject(SdToastProvider);
-  #sdModal = inject(SdModalProvider);
-
-  busyCount = $signal(0);
-  data = $signal<IData>({});
-
-  constructor() {
-    $effect([], async () => {
-      await this.#loadData();
-    });
-  }
-}
-```
-
-## Bootstrap
-
-```typescript
-sdHmrBootstrapAsync(AppPage, {
-  providers: [
-    provideRouter([...routes], withHashLocation()),
-    provideSdAngular({
-      clientName: "my-app",
-      defaultTheme: "compact",
-    }),
-  ],
-});
-```
-
-## Modal
-
-Implement `ISdModal<T>` interface:
-
-```typescript
-export class MyModal implements ISdModal<TResult> {
-  param = input<string>();
-  close = output<TResult>();
-}
-
-// Usage
-await this.#sdModal.showAsync({
-  type: MyModal,
-  title: "Title",
-  inputs: { param: "value" },
-});
-```
-
-## Data Sheet
-
-CRUD tables extend `AbsSdDataSheet<TFilter, TItem, TKey>`:
-
-- `search()` — query data
-- `submit()` — save changes
-- `downloadExcel()` / `uploadExcel()` — Excel integration
-- `$mark()` — mark dirty when cell is modified (mandatory)
-
-## Busy / Error Handling
-
-```typescript
-this.busyCount.update((v) => v + 1);
-try {
-  await this.#sdToast.try(async () => {
-    /* work */
-  });
-} finally {
-  this.busyCount.update((v) => v - 1);
-}
-```
-
-## Theming
-
-- Use CSS variables: `--theme-primary-default`, `--gap-sm`, `--border-radius-default`, etc.
-- Do not hardcode colors
-- Themes: `"compact"` | `"mobile"` | `"kiosk"` + dark mode
-
-## Permissions
-
-```typescript
-perms = usePermsSignal(["base.partner"], ["use", "edit"]);
-canEdit = $computed(() => this.perms().includes("edit"));
-```
-
-## Routing
-
-```typescript
-{
-  path: "my-page",
-  loadComponent: () => import("./MyPage").then((m) => m.MyPage),
-}
-```

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

@@ -1,155 +0,0 @@
-# Code Conventions
-
-## Generic Type Parameters
-
-- Always use descriptive names — single-letter `T` alone is not allowed
-- Use `T` prefix + descriptive name: `TItem`, `TData`, `TResult`, `TKey`, `TValue`, `TAuthInfo`
-
-## Prototype Extensions
-
-Importing `@simplysm/core-common` adds extension methods to Array, Map, Set:
-
-- `Array`: `single()`, `filterExists()`, `groupBy()`, `orderBy()`, etc.
-- `Map`: `getOrCreate()`, `update()`
-- `Set`: `adds()`, `toggle()`
-
-Before using extension methods: Verify actual existence in `@simplysm/core-common` extensions (check README or source). Do not guess methods that don't exist.
-
-## Function Naming Conventions
-
-- Do not use `Async` suffix on function names — Async is the default
-- When both sync and async versions exist, use `Sync` suffix on the sync function
-- **Exception — extensions**: When adding an async version to an existing prototype (e.g., `Array`), follow the original naming convention. If the sync method already exists without a `Sync` suffix, use `Async` suffix for the async version.
-
-```typescript
-// Good
-async function readFile() { ... }      // Async (default)
-function readFileSync() { ... }        // Sync version
-
-// Bad
-async function readFileAsync() { ... } // Async suffix prohibited
-
-// Exception — Array extension already has mapMany()
-Array.prototype.mapManyAsync = async function () { ... }  // OK
-```
-
-
-## File Naming
-
-- Auxiliary files (`types.ts`, `utils.ts`, etc.) must be prefixed with the main file name (e.g., `CrudSheet.types.ts`)
-- File names must be self-identifying without relying on the parent directory
-
-## JSDoc Convention
-
-- Not enforced — omit when code is self-explanatory
-- When written, use English
-
-## 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
-
-- Use `//` comments to group exports
-- Always `export *` (wildcard), never explicit `export type { ... } from "..."`
-
-## `#region` / `#endregion`
-
-- When splitting a large ts/tsx file has a bigger tradeoff than keeping it as-is, use `#region`/`#endregion` to organize sections within the file
-- Do not use in simple export files like index.ts
-
-## `any` vs `unknown` vs Generics
-
-Choose based on **what you do with the value**:
-
-| Type | When | Key rule |
-|------|------|----------|
-| `any` | Value is **passed through** without property access | No `.prop`, no method calls, no narrowing |
-| `unknown` | Value's properties **will be accessed** but type is unknown | Must narrow with type guard before any access |
-| Generic `<T>` | **Input/output type relationship** must be preserved | Caller's type flows through to return type |
-
-```typescript
-// any — pure pass-through, no property access
-function logAndStore(value: any): void {
-  console.log(value);   // OK: no property access
-  storage.push(value);  // OK: just forwarding
-}
-
-// unknown — will access properties, must narrow first
-function getName(data: unknown): string {
-  if (typeof data === "object" && data !== null && "name" in data) {
-    return String((data as { name: unknown }).name);
-  }
-  throw new Error("No name property");
-}
-
-// Generic — input type preserved in output
-function wrapValue<T>(value: T): { value: T } {
-  return { value };
-}
-```
-
-**any vs Generic for pass-through:** If the function only forwards a value without accessing it AND the caller does not need type preservation in the return, use `any`. If the caller needs the same type back (input→output relationship), use a generic.
-
-## 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)
-- **No `Record<string, any>` for structured props** — define explicit interfaces so consumers get autocomplete
-
-```typescript
-// Bad — consumers get no autocomplete, changes are invisible
-interface TableProps {
-  columns: Record<string, any>;
-  onRowClick: Function;
-}
-
-// Good — changes to ColumnDef break consumers at compile time
-interface TableProps<TRow> {
-  columns: ColumnDef<TRow>[];
-  onRowClick?: (row: TRow) => void;
-}
-```
-
-## Forced Type Casting Prohibition
-
-- **`as unknown as X` is prohibited** — dangerous escape hatch that silences real type errors
-- **`as X` must be avoided** unless there is no alternative — when tempted, try these fixes first:
-
-| Type error situation | Fix (instead of `as`) |
-|---------------------|-----------------------|
-| Missing properties | Add them to the interface |
-| Type too wide | Use generics to propagate correctly |
-| Unknown shape | Type guard: `if ("prop" in obj)`, `instanceof` |
-| Multiple shapes | Discriminated union or overload |
-| Wrong at source | Fix the root cause, not the usage site |
-
-```typescript
-// Bad — casting hides the real problem
-const admin = user as unknown as AdminUser;
-
-// Bad — lazy cast instead of proper narrowing
-const name = (event as any).target.name;
-
-// Good — fix parameter type at the source
-function getAdminDashboard(admin: AdminUser): string { ... }
-
-// Good — narrow unknown with type guard
-function getNameFromEvent(event: unknown): string {
-  if (typeof event === "object" && event !== null && "target" in event) {
-    const target = event.target;
-    if (typeof target === "object" && target !== null && "name" in target) {
-      return String(target.name);
-    }
-  }
-  throw new Error("Invalid event structure");
-}
-```
-
-## Boolean Prop Defaults
-
-- Name boolean props so their default value is `false`
-- Prefer `hide*`, `disable*` patterns where the feature is ON by default
-- This avoids double-negation in JSX: `hideX={false}` is clearer than `showX={true}` when both mean "show X"
-- Exception: inherent HTML attributes like `draggable` may default to `true`

package/claude/refs/sd-directories.md

@@ -1,7 +0,0 @@
-# Directory Reference
-
-- `.cache/`: Build cache (`eslint.cache`, `typecheck-{env}.tsbuildinfo`, `dts.tsbuildinfo`). Reset: delete `.cache/`
-- `.tmp/playwright/`: Playwright MCP output directory
-  - Screenshots/snapshots must always be saved to the `.tmp/playwright/` directory
-  - When calling `browser_take_screenshot`, always prefix filename with `.tmp/playwright/` (e.g., `.tmp/playwright/screenshot.png`)
-  - `PLAYWRIGHT_OUTPUT_DIR` only applies to auto-generated filenames; explicitly specified filenames are resolved relative to cwd

package/claude/refs/sd-library-issue.md

@@ -1,7 +0,0 @@
-# Simplysm Library Issue Reporting
-
-Source code for `@simplysm/*` packages can be found in `node_modules/@simplysm/`. If debugging reveals the root cause is in the simplysm library itself, generate a GitHub issue-formatted text (title, reproduction steps, expected behavior, actual behavior) and display it to the user.
-
-**Report facts only — do not suggest fixes or include code location hints. Do not auto-submit the issue — only display the text.**
-
-The issue body must NEVER include internal analysis of library code (class names, variable names, style properties, inheritance chains, etc.). Only describe user-observable symptoms.

package/claude/refs/sd-migration.md

@@ -1,7 +0,0 @@
-# Migration Rules
-
-When porting/migrating code from another codebase (e.g., v12 Angular → v13 SolidJS):
-
-1. **Analyze every line**: Read the original source and all its dependencies (imports, base classes, etc.) line by line. Understand every feature, prop, and behavior. If a dependency cannot be found, ask the user.
-2. **Ask about every difference**: Any change from the original (API, pattern, design, omission, addition) must be asked to the user. Never decide silently.
-3. **Verify after completion**: Compare the result 1:1 with the original and report any omissions or differences to the user.