@zokizuan/satori-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ham-zax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @zokizuan/satori-cli
+
+Shell CLI for Satori installation, skill packaging, and direct tool invocation without a resident MCP client.
+
+## What It Does
+
+- installs and removes Satori MCP client config for supported clients
+- copies packaged first-party skills:
+  - `satori-search`
+  - `satori-navigation`
+  - `satori-indexing`
+- starts a local stdio session against `@zokizuan/satori-mcp` for direct shell workflows
+
+## Install / Uninstall
+
+```bash
+npx -y @zokizuan/satori-cli@0.1.1 install --client codex
+npx -y @zokizuan/satori-cli@0.1.1 install --client claude
+npx -y @zokizuan/satori-cli@0.1.1 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.1.1 uninstall --client codex
+```
+
+Managed install writes MCP config that launches:
+
+```toml
+[mcp_servers.satori]
+command = "npx"
+args = ["-y", "@zokizuan/satori-mcp@4.4.1"]
+startup_timeout_ms = 180000
+```
+
+## Commands
+
+```bash
+satori-cli tools list
+satori-cli tool call <toolName> --args-json '{"path":"/abs/repo","query":"auth"}'
+satori-cli tool call <toolName> --args-file ./args.json
+satori-cli tool call <toolName> --args-json @-
+satori-cli <toolName> [schema-subset flags]
+```
+
+Global flags (`--startup-timeout-ms`, `--call-timeout-ms`, `--format`, `--debug`) must appear before the command token.
+
+## Development
+
+```bash
+pnpm --filter @zokizuan/satori-cli build
+pnpm --filter @zokizuan/satori-cli test
+pnpm --filter @zokizuan/satori-cli release:smoke
+```

package/assets/skills/satori-indexing/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: satori-indexing
+description: Index lifecycle and remediation for Satori. Use when codebases are not indexed, stale, blocked, or need freshness recovery.
+---
+
+# Satori Indexing
+
+Use this skill when the task is to create, reindex, sync, inspect readiness, or recover from stale index state.
+
+## Tools
+
+Use only:
+1. `list_codebases`
+2. `manage_index`
+
+## Workflow
+
+1. Use `list_codebases` for a global view of tracked roots.
+2. Use `manage_index(action="status", path=...)` for the specific codebase.
+3. Use `manage_index(action="create", path=...)` when the codebase is not indexed.
+4. Use `manage_index(action="reindex", path=...)` only for compatibility gates or explicit rebuilds.
+5. Use `manage_index(action="sync", path=...)` for freshness convergence and ignore-rule updates.
+
+## Rules
+
+- If any tool returns `requires_reindex`, stop and reindex. Do not substitute `sync`.
+- Never call `manage_index(action="clear")` unless the user explicitly requests destructive reset.
+- Treat ignore-only churn as a `sync` problem first.
+- Respect blocked and indexing states instead of forcing retries blindly.
+
+## Status Handling
+
+- `requires_reindex`: run `manage_index(action="reindex")`.
+- `not_ready` with indexing reason: check status and wait for terminal completion.
+- `not_indexed`: create the index.
+- Ignore-rule noise mitigation: update `.satoriignore`, wait debounce, and run `sync` for immediate convergence.

package/assets/skills/satori-navigation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: satori-navigation
+description: Deterministic symbol navigation with Satori. Use after search results are found to lock exact spans and inspect call relationships.
+---
+
+# Satori Navigation
+
+Use this skill after `search_codebase` has returned candidate results and you need exact symbol/file navigation.
+
+## Tools
+
+Use only:
+1. `file_outline`
+2. `call_graph`
+3. `read_file`
+
+## Workflow
+
+1. Use grouped `search_codebase` results as the starting point.
+2. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
+3. If `callGraphHint.supported=false`, execute `navigationFallback.readSpan.args` exactly.
+4. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock the symbol span.
+5. Use `read_file(path=..., open_symbol=...)` or deterministic line spans for the final read.
+
+## Rules
+
+- Treat `navigationFallback` as authoritative. Do not invent spans.
+- `open_symbol` must resolve deterministically. Do not guess on ambiguity.
+- `read_file(mode="annotated")` is preferred when outline metadata is useful.
+- Follow continuation hints when plain reads are truncated.
+
+## Remediation
+
+- `requires_reindex`: reindex before retrying navigation.
+- `not_ready`: wait for indexing to finish.
+- `unsupported`: fall back to deterministic `read_file` spans when supplied by `navigationFallback`.

package/assets/skills/satori-search/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: satori-search
+description: Semantic-first code search with Satori. Use for intent-based code discovery before file reads or grep.
+---
+
+# Satori Search
+
+Use this skill when the task is to find where behavior lives, identify candidate symbols, or narrow the search space before deeper navigation.
+
+## Tools
+
+Use only:
+1. `list_codebases`
+2. `manage_index`
+3. `search_codebase`
+
+## Workflow
+
+1. Check readiness with `manage_index(action="status", path=...)`.
+2. If not indexed, use `manage_index(action="create", path=...)`.
+3. If `requires_reindex` appears, stop and use `manage_index(action="reindex", path=...)`, then retry.
+4. Search with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
+
+## Search Rules
+
+- Start with natural-language intent, not filenames.
+- Default to `scope="runtime"`.
+- Use operators only when needed: `lang:`, `path:`, `-path:`, `must:`, `exclude:`.
+- Treat warnings as usable-but-degraded results, not fatal errors.
+- Use `debug=true` only when ranking or filter explanations are required.
+
+## Remediation
+
+- `requires_reindex`: run `manage_index(action="reindex")`, not `sync`.
+- `not_ready` with indexing reason: wait or check `manage_index(action="status")`.
+- Noise mitigation hint: update `.satoriignore`, wait debounce, rerun search, and use `manage_index(action="sync")` only for immediate convergence.

package/dist/args.d.ts

@@ -0,0 +1,54 @@
+export interface GlobalOptions {
+    startupTimeoutMs: number;
+    callTimeoutMs: number;
+    format: "json" | "text";
+    debug: boolean;
+}
+export type RawArgsMode = {
+    kind: "none";
+} | {
+    kind: "json";
+    value: string;
+} | {
+    kind: "file";
+    path: string;
+} | {
+    kind: "stdin-json";
+};
+export type ParsedCommand = {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "install";
+    client: InstallClient;
+    dryRun: boolean;
+} | {
+    kind: "uninstall";
+    client: InstallClient;
+    dryRun: boolean;
+} | {
+    kind: "tools-list";
+} | {
+    kind: "tool-call";
+    toolName: string;
+    rawArgsMode: RawArgsMode;
+} | {
+    kind: "wrapper";
+    toolName: string;
+    rawArgsMode: RawArgsMode;
+    wrapperArgs: string[];
+};
+export interface ParsedCliInput {
+    globals: GlobalOptions;
+    command: ParsedCommand;
+}
+export interface ResolveRawArgsOptions {
+    stdin?: NodeJS.ReadStream;
+    stdinTimeoutMs: number;
+}
+export type InstallClient = "all" | "claude" | "codex";
+export declare function parseCliArgs(argv: string[]): ParsedCliInput;
+export declare function resolveRawArguments(rawArgsMode: RawArgsMode, options: ResolveRawArgsOptions): Promise<Record<string, unknown>>;
+export declare function parseWrapperArgumentsFromSchema(toolName: string, inputSchema: unknown, wrapperArgs: string[]): Record<string, unknown>;
+//# sourceMappingURL=args.d.ts.map