emdash-emit 0.1.8 → 0.1.9

package/README.md

@@ -32,7 +32,7 @@
   - [Media Management & Upload Workflow](#media-management--upload-workflow)
 - [🤖 The Golden Path for AI & Humans (4-Step Cycle)](#-the-golden-path-for-ai--humans-4-step-cycle)
   - [The 4-Step Authoring Cycle](#the-4-step-authoring-cycle)
-  - [Preflight Safety Guardrails (G1–G11)](#preflight-safety-guardrails-g1g11)
+  - [Preflight Safety Guardrails (G1–G12)](#preflight-safety-guardrails-g1g12)
 - [🛠 CLI Command Reference](#-cli-command-reference)
   - [`emit init`](#emit-init)
   - [`emit profile`](#emit-profile)
@@ -193,6 +193,9 @@ emit profile add my-blog \
 > [!NOTE]
 > Profiles are securely stored with `0600` permissions at `~/.config/emit/profiles.yaml` (on macOS / Linux) or `%USERPROFILE%\.config\emit\profiles.yaml` (on Windows).
 
+> [!NOTE]
+> **`emit profile add` updates in place.** Re-running it with only `--origin` (for example after rotating a domain) keeps the stored `--token` and the `--workspace` link that `emit init` created, and reports `Kept the existing token and workspace link`. Pass `--token`/`--workspace` explicitly to replace them; an empty `--token ''` clears the credential on purpose.
+
 ### 2. Initialize a Workspace
 
 Navigate to your local repository directory and initialize it:
@@ -202,7 +205,7 @@ cd /path/to/local/blog-repo
 emit init
 ```
 
-This creates the `.emit/` directory with a default `config.json` and initializes the local baseline cache SQLite database (`.emit/cache.db`).
+This creates the `.emit/` directory with `config.json` (inheriting `origin` from your resolved profile when `--origin` is omitted, and automatically linking `workspace` back into `~/.config/emit/profiles.yaml` unless `--no-link` is passed) and initializes the local baseline cache SQLite database (`.emit/cache.db`).
 
 ### 3. Multi-Site Management (Directory-Driven & Zero Friction)
 
@@ -222,7 +225,7 @@ emit profile list
 ```
 
 **How Automatic Profile Resolution Works:**
-1. **Directory-Driven Auto Detection (Recommended)**: When you `cd ~/blogs/personal` and run `emit pull`, `emit push`, or launch an AI agent, Emit detects your current folder and automatically uses the `personal` profile. When you `cd ~/blogs/work`, it seamlessly connects to `work`.
+1. **Directory-Driven Auto Detection (Recommended)**: When you `cd ~/blogs/personal` and run `emit pull`, `emit push`, or launch an AI agent, Emit detects your current folder and automatically uses the `personal` profile. When you `cd ~/blogs/work`, it seamlessly connects to `work`. Directory comparison is symlink-safe (`fs.realpathSync`), so a workspace reached through a symlinked path (or a macOS `/tmp`-style alias) still resolves to the right profile.
 2. **Explicit Profile Flag**: You can explicitly specify `--profile <name>` (or pass `profile: "<name>"` in MCP) from any directory to override automatic detection.
 3. **Ambiguity Safeguard**: If you run a command outside of any registered workspace and omit `--profile`, Emit aborts with an `AmbiguousProfileError` instead of guessing or silently pushing to the wrong site.
 
@@ -230,7 +233,7 @@ emit profile list
 
 Emit resolves authentication credentials using a strict 4-tier priority chain (`src/client/auth.ts`):
 
-1. **Environment Variables (`EMDASH_TOKEN` or `EMDASH_API_TOKEN`, plus optional `EMDASH_ORIGIN`)**: Highest priority; ideal for CI/CD pipelines and one-off overrides.
+1. **Environment Variables (`EMDASH_TOKEN` or `EMDASH_API_TOKEN`)**: Highest priority; ideal for CI/CD pipelines and one-off overrides. `EMDASH_ORIGIN` (and `EMDASH_WORKSPACE`) are read here as well and documented under [Origin Resolution Precedence](#origin-resolution-precedence).
 2. **Site Profile Registry (`~/.config/emit/profiles.yaml`)**: Matched via `--profile <name>` (or MCP `profile`), current workspace directory auto-detection, or a single registered profile.
 3. **EmDash CLI Credentials (`~/.config/emdash/auth.json`)**: Fallback when no token is configured in the profile.
 4. **Emit Custom Credentials (`~/.config/emit/credentials.json`)**: Final fallback.
@@ -238,6 +241,19 @@ Emit resolves authentication credentials using a strict 4-tier priority chain (`
 **Automatic OAuth Token Refresh on HTTP 401 (`src/client/http.ts`)**:
 When credentials include a `refresh_token` (such as OAuth sessions in `~/.config/emdash/auth.json` or `~/.config/emit/credentials.json`) and a request returns `401 Unauthorized`, Emit automatically exchanges the `refresh_token` at `POST /_emdash/api/auth/token` (`grant_type: "refresh_token"`), persists the refreshed token back to `auth.json` when applicable, and transparently retries the request once.
 
+#### Origin Resolution Precedence
+
+The target instance (`origin`) is resolved by one shared function (`resolveOriginPriority()` in `src/cli/context.ts`, reused by the MCP server) so CLI and MCP always agree:
+
+1. **Explicitly selected profile** — `--profile <name>` (or MCP `profile: "<name>"`)
+2. **`EMDASH_ORIGIN`** — overrides an *implicitly* resolved profile so CI/staging overrides actually take effect
+3. **Auto-resolved profile** — current-directory match, unique origin match, or the single registered profile
+4. **Resolved auth origin** — carried by `~/.config/emdash/auth.json` / `~/.config/emit/credentials.json`
+5. **Workspace `.emit/config.json`** → then the `https://example.com` sentinel default
+
+> [!NOTE]
+> Every silent override is surfaced as a `⚠️ Warning` naming the **real source** of each value (`.emit/config.json` values are never mislabeled as `EMDASH_ORIGIN` or the reverse). When you select `--profile` explicitly, `EMDASH_ORIGIN` is ignored **and reported**. Comparisons ignore trailing slashes. `emit init` follows the same ranking (`--origin` > `EMDASH_ORIGIN` > auto-resolved profile) and refuses to link the workspace to a profile whose origin does not match the initialized origin.
+
 ### 5. Workspace Configuration (`.emit/config.json`)
 
 Running `emit init` generates `.emit/config.json` with the following keys (`src/utils/config.ts`):
@@ -255,10 +271,10 @@ Running `emit init` generates `.emit/config.json` with the following keys (`src/
 
 | Key | Default | Description |
 | --- | --- | --- |
-| `origin` | `"https://example.com"` | Base URL of the target EmDash instance (overridden by `EMDASH_ORIGIN` or active profile) |
+| `origin` | `"https://example.com"` | Base URL of the target EmDash instance, exactly as written to disk. It is never rewritten in-memory by `EMDASH_ORIGIN`; see [Origin Resolution Precedence](#origin-resolution-precedence) for how the effective origin is chosen |
 | `defaultCollection` | `"posts"` | Default content collection when `--collection` is omitted |
 | `defaultLocale` | `"ja"` | Default locale used when scaffolding new drafts via `emit new` / `sync_new` |
-| `postsSyncLimit` | `100` | Sliding window size for batch article pulls (also supports legacy `syncLimit` fallback) |
+| `postsSyncLimit` | `100` | Sliding window size for batch article pulls (when `status: all`, fetches up to `postsSyncLimit` `published` + up to `postsSyncLimit` `draft` articles in parallel; also supports legacy `syncLimit` fallback) |
 | `mediaSyncLimit` | `300` | Default maximum items fetched by `emit pull-media` / `sync_pull_media` |
 | `concurrency` | `8` | Parallel HTTP fetch concurrency during batch pulls |
 
@@ -320,8 +336,10 @@ your-blog/
 └── posts/                          # Local Markdown Articles (<yyyyMMdd>_<ulid>-<title>.md)
     ├── draft/                      # Draft articles (named after title; falls back to slug if empty)
     │   └── 20261104_01M6...-My-New-Post.md
-    └── published/                  # Live published articles
-        └── 20261015_01M5...-Getting-Started.md
+    ├── published/                  # Live published articles
+    │   └── 20261015_01M5...-Getting-Started.md
+    └── conflicts/                  # Read-only rescue copies of divergent local content (written by pull; never pushed or pruned)
+        └── 20261101_01M5...-Getting-Started.conflict.md
 
 ```
 
@@ -333,7 +351,7 @@ Emit maintains a local SQLite database via Node.js built-in `node:sqlite` (`src/
 | --- | --- |
 | `entries` | Caches the latest remote JSON envelope and revision (`rev`) for each synced article |
 | `base_snapshots` | Stores the baseline Markdown body and baseline frontmatter at the last synced revision to power Hybrid 3-Way Merge (`frontmatter_yaml` holds a **JSON-encoded** `Frontmatter` object, not YAML text) |
-| `sync_state` | Tracks each article's workspace-relative file path and SHA-256 content hash to detect local modifications (`synced` vs `modified`) |
+| `sync_state` | Tracks each article's workspace-relative file path and SHA-256 content hash to detect local modifications (`synced` vs `modified` vs `untracked`, plus `invalid` when YAML frontmatter fails parsing; `invalid` files are excluded from `emit push --all`, cached `invalid` files are automatically self-healed on batch `emit pull` / `sync_pull`, and uncached `invalid` files outside the sliding window can be repaired via `emit pull <ULID>` or `sync_pull(id: "<ULID>")`) |
 | `bylines` | Caches remote author records (`id`, `slug`, `display_name`, `is_guest`) synced automatically via `/_emdash/api/mcp` (`byline_list`) on pull, enabling slug ⇔ ULID resolution and default author selection |
 | `media_state` | Tracks offline draft image uploads (`local_hash`, `media_id`, `storage_key`, `url`, `workspace_path`, `status`: `pending` \| `uploaded` \| `ready` \| `failed`) for idempotency, retry recovery, and cross-article asset reuse |
 
@@ -487,9 +505,9 @@ Whether you are a human developer or an autonomous AI agent (Antigravity, Claude
 * To push a draft: `emit push posts/draft/<filename>.md`
 * To publish live: update `status: published` and run `emit push posts/draft/<filename>.md --allow-publish`.
 
-### Preflight Safety Guardrails (G1–G11)
+### Preflight Safety Guardrails (G1–G12)
 
-To ensure autonomous AI agents and automated scripts cannot corrupt workspace state or accidentally publish unintended content, Emit enforces 11 strict preflight guardrails before executing any write operation:
+To ensure autonomous AI agents and automated scripts cannot corrupt workspace state or accidentally publish unintended content, Emit enforces 12 strict preflight guardrails before executing any write operation:
 
 | Guard | Code Name | Description | Severity |
 | --- | --- | --- | --- |
@@ -504,6 +522,7 @@ To ensure autonomous AI agents and automated scripts cannot corrupt workspace st
 | **G9** | `MODIFIED_OPAQUE_BLOCK` | Verifies that `<!--ec:block ... -->` opaque fences have not been tampered with or corrupted | Error |
 | **G10** | `INVALID_FEATURED_IMAGE` | Verifies that `featuredImage` is a 26-character canonical media ULID (normalized to uppercase) or `null`. A remote media URL that contains a ULID is resolved with a warning; local file paths and malformed values are rejected | Error |
 | **G11** | `LOCAL_IMAGE_AUTO_UPLOAD` (`MISSING_LOCAL_IMAGE_FILE` / `INVALID_LOCAL_IMAGE_TYPE` / `LOCAL_IMAGE_SIZE_EXCEEDED` / `PROMOTED_MEDIA_NOT_FOUND_REMOTE` / `[MEDIA_EXISTENCE_UNVERIFIED]`) | Detects standalone `media/drafts/<file>` image lines (or reuses an already-promoted `media/` asset across articles), validates file existence, extension, and size (≤ 50 MiB), queues them for automatic upload, URL rewrite, and `media/` promotion during `push`, and verifies every reused asset against `GET /_emdash/api/media/{id}` before its URL is baked into the body | Info / Warning / Error |
+| **G12** | `QUARANTINED_COPY_NOT_PUSHABLE` | Refuses to push a rescue copy under `posts/conflicts/` (written by a pull that found divergent local content) before any network request, because it would overwrite the canonical article of the same ULID with stale content and recreate duplicate local files | Error |
 
 ---
 
@@ -607,13 +626,13 @@ emit pull [id] [options]
 ```
 
 * `[id]`: Optional article ID or ULID. If specified, pulls only that specific article (even if outside the window). Taxonomies are not pulled in single-article mode.
-* `-s, --status <draft|published|all>`: Filter by publication status (default: `all`).
+* `-s, --status <draft|published|all>`: Filter by publication status (default: `all`). When set to `all`, the sliding window (`postsSyncLimit`, default `100`) is applied **per status** (fetching up to `postsSyncLimit` `published` + up to `postsSyncLimit` `draft` articles in parallel).
 * `-c, --collection <collection>`: Collection name (default: `posts`).
 * `--no-prune`: Do not prune local articles that have fallen outside the sliding window (escape hatch; not intended for routine use).
 * `--force`: Force overwrite local files and bypass differential hash checking.
 * `--concurrency <n>`: Parallel processing task limit (default: `8`).
 * `--posts-only`: Skip automatic remote taxonomy sync. Pulls articles only (local taxonomy candidates hint is still displayed from cached definitions).
-* `--media`: Also pull media assets and companion metadata into `media/`.
+* `--media`: Also pull media assets and companion metadata into `media/` (bounded by `mediaSyncLimit`, default `300`). Use `emit pull-media` for `--limit`, `--all`, and `--prune` control.
 * `--metadata-only`: With `--media`: download only metadata YAML, skip binary file downloads.
 
 > [!NOTE]
@@ -621,7 +640,10 @@ emit pull [id] [options]
 
 > [!NOTE]
 > **Why `--no-prune` is rarely needed:**  
-> Automatic pruning is mathematically loss-free: Emit's unpushed edits safeguard strictly aborts the pull if an older article contains local modifications. You only need `--no-prune` in exceptional circumstances, such as temporarily suppressing Git working-tree changes during a quick pull.
+> Automatic pruning is mathematically loss-free: Emit's unpushed edits safeguard inspects both the canonical file and any duplicate filenames sharing the same 26-character ULID, strictly aborting the pull (`SyncPruneConflictError`) if any of them contain local modifications. Clean duplicate files are removed alongside the canonical file. You only need `--no-prune` in exceptional circumstances, such as temporarily suppressing Git working-tree changes during a quick pull.
+
+> [!NOTE]
+> **Unpushed writing is never discarded.** When a pull finds local content that diverges from the last synced baseline, Emit first moves that file to `posts/conflicts/<name>.conflict.md` (a read-only rescue copy) and then writes the canonical article. Rescue copies are never pushed or pruned automatically, and pushing one directly is refused with `QUARANTINED_COPY_NOT_PUSHABLE` (Guard **G12**): read the copy, merge any valuable content into the canonical article, then delete it. If an invalid file also carries local edits, `--force` is the escape hatch (it quarantines the divergent copy, then writes the repaired file).
 
 **Example:**
 
@@ -656,11 +678,11 @@ Available Categories:
 Available Tags:
   - ai, cloudflare, emit, typescript
 
-Fetching articles from remote (posts, status: all, window: 100, concurrency: 8)...
-  [1/100] ✅ Pulled hello-world -> posts/published/20261101_01M5...-Hello-World.md
-  [2/100] ✅ Pulled draft-post -> posts/draft/20261104_01M6...-Draft-Post.md
+Fetching articles from remote (posts, status: all, window: 100/status, concurrency: 8)...
+  [1/169] ✅ Pulled hello-world -> posts/published/20261101_01M5...-Hello-World.md
+  [2/169] ✅ Pulled draft-post -> posts/draft/20261104_01M6...-Draft-Post.md
 
-🎉 Articles: 100 total (12 updated, 88 skipped/up-to-date)
+🎉 Articles: 169 total [100 published, 69 draft] (12 updated, 157 skipped/up-to-date)
 
 ```
 
@@ -709,13 +731,17 @@ emit status [-c, --collection <collection>] [-p, --profile <name>]
   🟡 [modified] draft     posts/draft/20261104_01M6BBB...-AI-Workflow-Guide.md (AI Workflow Guide)
   ⚪ [untracked] draft     posts/draft/20261104_01M6AAA...-Draft-Notes.md (Draft Notes)
   🟢 [synced  ] published posts/published/20261015_01M5ZZZ...-Getting-Started.md (Getting Started)
+  🔴 [invalid ] published posts/published/20190405_01M6CCC...-Broken-Post.md (Broken-Post) [uncached] — bad indentation of a mapping entry at line 5
 
-Summary: 3 total (1 synced, 1 modified, 1 untracked)
+Summary: 4 total (1 synced, 1 modified, 1 untracked, 1 invalid)
 ```
 
 > [!NOTE]
 > Articles are sorted newest-first by date prefix and ULID. The date prefix reflects the article's publication or creation date, not the last-modified time. To locate currently active edits, look for files marked `[modified]`.
 
+> [!NOTE]
+> `[invalid]` marks a file whose YAML frontmatter could not be parsed (usually an older serializer wrote unquoted percent-encoded taxonomy slugs). Batch `emit pull` self-heals cached invalid files; files outside the sliding window are marked `[uncached]` and are repaired with `emit pull <ULID>` (MCP: `sync_pull` with `id: "<ULID>"`). When `<collection>/conflicts/` holds rescue copies, the count is reported separately (`conflicts`) and never counted as an article.
+
 ---
 
 ### `emit diff`
@@ -735,7 +761,7 @@ emit diff [filePath] [-i, --id <id>] [-p, --profile <name>]
 
 ### `emit pull-taxonomies`
 
-Downloads categories and tags from EmDash and generates local YAML definitions under `categories/` and `tags/`. This is also performed automatically by `emit pull` in batch mode.
+Downloads categories and tags from EmDash and generates local YAML definitions under `categories/` and `tags/`. This is also performed automatically by `emit pull` in batch mode. If one taxonomy endpoint fails, existing local definitions for that taxonomy are preserved with a warning; if both endpoints fail, the command exits with code `1`.
 
 ```bash
 emit pull-taxonomies
@@ -851,16 +877,19 @@ Emit features a first-class **Model Context Protocol (MCP)** server over stdio.
 
 | Tool | Purpose | Key Parameters |
 | --- | --- | --- |
-| `sync_status` | Inspect local sync state (articles returned newest-first) | `collection`, `profile` |
-| `sync_pull` | Pull remote articles **and taxonomies** into local workspace (includes taxonomy hints) | `collection`, `id`, `filePath`, `status`, `force`, `noPrune`, `prune`, `postsOnly`, `includeMedia`, `metadataOnly`, `profile` |
+| `sync_status` | Inspect local sync state (articles newest-first, plus `invalid` and `conflicts` diagnostics) | `collection`, `profile` |
+| `sync_pull` | Pull remote articles **and taxonomies** into local workspace (includes taxonomy hints; preserves divergent local copies under `posts/conflicts/`) | `collection`, `id`, `filePath`, `status`, `force`, `noPrune`, `prune`, `postsOnly`, `includeMedia`, `metadataOnly`, `profile` |
 | `sync_new` | Scaffold new article with canonical ULID, frontmatter, default byline, and taxonomy hints | `slug` (required), `title`, `collection`, `locale`, `byline`, `profile` |
-| `sync_push` | Push local article changes to remote with preflight checks and `media/drafts/*` auto-upload | `filePath` (required), `allowPublish`, `profile` |
+| `sync_push` | Push local article changes to remote with preflight checks and `media/drafts/*` auto-upload; refuses `posts/conflicts/` rescue copies (G12) | `filePath` (required), `allowPublish`, `profile` |
 | `sync_diff` | Inspect diff between working file and baseline snapshot | `filePath`, `id`, `profile` |
 | `sync_pull_taxonomies` | Pull remote category and tag definitions (standalone; returns taxonomy hints) | `profile` |
 | `sync_pull_media` | Pull remote media files and metadata into `media/` | `limit`, `all`, `downloadFiles`, `profile` |
 | `profile_list` | List all configured connection profiles | (none) |
 | `profile_switch` | Switch active profile for multi-site environments | `name` (required), `persist` |
 
+> [!NOTE]
+> **Every tool failure is a structured result, never a raw throw.** Handlers return `isError: true` with the same diagnostics the CLI prints — `[CODE]`, HTTP status, endpoint, and a `💡 Suggestion` line (or a `PREFLIGHT_VALIDATION_FAILED` JSON payload with guard codes). This includes workspace/profile resolution failures, which list the available profiles so the agent can retry with an explicit `profile` argument.
+
 ### Autonomous Agent Workflows
 
 With Emit connected via MCP, you can give high-level natural language instructions to your AI:
@@ -924,6 +953,12 @@ Push your changes with 'emit push <file>' or discard them before pulling.
 
 **Solution**: Run `emit pull` or `sync_pull` (taxonomies are synced automatically), or use `emit pull-taxonomies` standalone to refresh your local category and tag list. Preflight Guard G4 will guide you with valid options.
 
+### Q: `[NETWORK_ERROR]`: Network request failed (`fetch failed`)
+
+**Cause**: The configured origin URL is unreachable due to DNS resolution failure, offline network/VPN state, or an incorrect origin in `~/.config/emit/profiles.yaml` or `.emit/config.json`.
+
+**Solution**: Verify the `origin` URL reported in `Endpoint:` and check `emit profile list` / `.emit/config.json`. If `.emit/config.json` and your active profile point to different origins, Emit prints an origin mismatch warning to help you reconcile them.
+
 ---
 
 ## 🧪 Testing & Quality Assurance

package/dist/cli/commands/profile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/profile.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuF9D"}
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/profile.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0I9D"}

package/dist/cli/commands/profile.js

@@ -21,6 +21,17 @@
  */
 import { loadProfilesFile, setProfile, setActiveProfile, removeProfile, resolveTargetProfile, } from '../../utils/profile.js';
 export function registerProfileCommands(program) {
+    /**
+     * Profile management is local-file work, and its failures (unknown profile name, ambiguous
+     * multi-profile resolution) are user-correctable. Report them as one actionable line with a
+     * non-zero exit instead of leaking a raw Node stack trace, matching how pull/push already
+     * format errors.
+     */
+    const reportProfileFailure = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`❌ ${message}`);
+        process.exit(1);
+    };
     const profileCmd = program
         .command('profile')
         .description('Manage EmDash site connection profiles (multi-site support)');
@@ -58,31 +69,67 @@ export function registerProfileCommands(program) {
         .option('--workspace <path>', 'Default local workspace directory for this site')
         .option('--active', 'Set this profile as active immediately')
         .action((name, options) => {
-        setProfile(name, {
-            origin: options.origin,
-            token: options.token,
-            workspace: options.workspace,
-        });
-        if (options.active) {
-            setActiveProfile(name);
+        try {
+            /**
+             * `add` doubles as "update", so unspecified options must fall back to what is already
+             * stored. Re-running `emit profile add <name> --origin <new>` used to rebuild the entry
+             * from scratch, silently wiping a stored token and the workspace link that `emit init`
+             * created - the next command then failed with "No authentication found" and directory
+             * based profile resolution broke.
+             */
+            const existing = loadProfilesFile().profiles[name];
+            const token = options.token ?? existing?.token ?? '';
+            const workspace = options.workspace ?? existing?.workspace;
+            const profileConfig = {
+                origin: options.origin,
+                token,
+                ...(workspace ? { workspace } : {}),
+                ...(existing?.defaultCollection ? { defaultCollection: existing.defaultCollection } : {}),
+                ...(existing?.defaultLocale ? { defaultLocale: existing.defaultLocale } : {}),
+            };
+            setProfile(name, profileConfig);
+            if (options.active) {
+                setActiveProfile(name);
+            }
+            const kept = [];
+            if (!options.token && existing?.token)
+                kept.push('token');
+            if (!options.workspace && workspace)
+                kept.push('workspace link');
+            console.log(`✅ Profile "${name}" ${existing ? 'updated' : 'configured'} successfully.` +
+                (kept.length
+                    ? ` Kept the existing ${kept.join(' and ')}; pass --token/--workspace to replace them.`
+                    : ''));
+        }
+        catch (error) {
+            reportProfileFailure(error);
         }
-        console.log(`✅ Profile "${name}" configured successfully.`);
     });
     // emit profile use <name>
     profileCmd
         .command('use <name>')
         .description('Set active default profile')
         .action((name) => {
-        setActiveProfile(name);
-        console.log(`✅ Active profile set to "${name}".`);
+        try {
+            setActiveProfile(name);
+            console.log(`✅ Active profile set to "${name}".`);
+        }
+        catch (error) {
+            reportProfileFailure(error);
+        }
     });
     // emit profile remove <name>
     profileCmd
         .command('remove <name>')
         .description('Remove a profile')
         .action((name) => {
-        removeProfile(name);
-        console.log(`✅ Profile "${name}" removed.`);
+        try {
+            removeProfile(name);
+            console.log(`✅ Profile "${name}" removed.`);
+        }
+        catch (error) {
+            reportProfileFailure(error);
+        }
     });
     // emit profile current
     profileCmd
@@ -90,7 +137,14 @@ export function registerProfileCommands(program) {
         .description('Show currently resolved profile and origin')
         .option('-p, --profile <name>', 'Explicit profile name to inspect')
         .action((options) => {
-        const resolved = resolveTargetProfile({ profile: options.profile });
+        let resolved;
+        try {
+            resolved = resolveTargetProfile({ profile: options.profile });
+        }
+        catch (error) {
+            reportProfileFailure(error);
+            return;
+        }
         if (!resolved) {
             console.log('No profile resolved (relying on environment variables or defaults).');
             return;

package/dist/cli/commands/profile.js.map

@@ -1 +1 @@
-{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../../src/cli/commands/profile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../../src/cli/commands/profile.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/pull.d.ts

@@ -1,4 +1,9 @@
 import type { Command } from 'commander';
 import type { CliContextResolver } from '../context.js';
+export declare function formatPullWindowLabel(status: string | undefined, limit: number): string;
+export declare function formatPullStatusBreakdown(status: string | undefined, items: Array<{
+    deleted?: boolean;
+    status?: string;
+}>): string;
 export declare function registerPullCommands(program: Command, resolveContext: CliContextResolver): void;
 //# sourceMappingURL=pull.d.ts.map

package/dist/cli/commands/pull.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/pull.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAyO/F"}
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/pull.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,KAAK,CAAC;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACnD,MAAM,CAKR;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,kBAAkB,GAAG,IAAI,CA4R/F"}

package/dist/cli/commands/pull.js

@@ -19,10 +19,21 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { pullArticle } from '../../sync/pull.js';
+import { pullArticle, formatQuarantineNotice } from '../../sync/pull.js';
 import { pullBatch, SyncPruneConflictError } from '../../sync/orchestrator.js';
 import { pullTaxonomies, getLocalTaxonomiesSummary, formatTaxonomiesHint, } from '../../sync/taxonomies.js';
 import { pullMedia } from '../../sync/media.js';
+import { ApiError } from '../../client/error.js';
+export function formatPullWindowLabel(status, limit) {
+    return status === 'all' ? `${limit}/status` : `${limit}`;
+}
+export function formatPullStatusBreakdown(status, items) {
+    if (status !== 'all')
+        return '';
+    const publishedCount = items.filter((i) => !i.deleted && i.status === 'published').length;
+    const draftCount = items.filter((i) => !i.deleted && i.status === 'draft').length;
+    return ` [${publishedCount} published, ${draftCount} draft]`;
+}
 export function registerPullCommands(program, resolveContext) {
     // emit pull [id]
     program
@@ -80,7 +91,8 @@ export function registerPullCommands(program, resolveContext) {
                 const concurrency = options.concurrency
                     ? parseInt(options.concurrency, 10)
                     : ctx.config.concurrency || 8;
-                console.log(`Fetching articles from remote (${collection}, status: ${options.status}, window: ${limit}, concurrency: ${concurrency})...`);
+                const windowLabel = formatPullWindowLabel(options.status, limit);
+                console.log(`Fetching articles from remote (${collection}, status: ${options.status}, window: ${windowLabel}, concurrency: ${concurrency})...`);
                 const batchResult = await pullBatch({
                     collection,
                     workspaceRoot: ctx.root,
@@ -97,6 +109,9 @@ export function registerPullCommands(program, resolveContext) {
                         if (item.deleted) {
                             console.log(`  [${current}/${total}] 🗑️  Pruned ${item.slug} -> ${item.filePath}`);
                         }
+                        else if (item.localEditsPreserved) {
+                            console.log(`\n  [${current}/${total}] 🛡️  Kept local edits for ${item.slug} (${item.filePath})`);
+                        }
                         else if (!item.skipped) {
                             console.log(`  [${current}/${total}] ✅ Pulled ${item.slug} -> ${item.filePath}`);
                         }
@@ -110,7 +125,17 @@ export function registerPullCommands(program, resolveContext) {
                     return;
                 }
                 const deletedMsg = batchResult.deleted ? `, ${batchResult.deleted} pruned` : '';
-                console.log(`\n🎉 Articles: ${batchResult.total} total (${batchResult.updated} updated, ${batchResult.skipped} skipped/up-to-date${deletedMsg})`);
+                const statusBreakdown = formatPullStatusBreakdown(options.status, batchResult.items);
+                console.log(`\n🎉 Articles: ${batchResult.total} total${statusBreakdown} (${batchResult.updated} updated, ${batchResult.skipped} skipped/up-to-date${deletedMsg})`);
+                if (batchResult.preserved && batchResult.preserved > 0) {
+                    console.log(`🛡️  ${batchResult.preserved} article(s) had unpushed local edits: Emit kept your local version (remote changes were NOT applied). ` +
+                        `Push them with "emit push <filePath>", or re-run with --force to accept the remote version.`);
+                }
+                for (const item of batchResult.items) {
+                    const notice = formatQuarantineNotice(item.quarantined);
+                    if (notice)
+                        console.log(`\n${notice}`);
+                }
                 // 3. Pull media (if --media)
                 if (includeMedia) {
                     const mediaLimit = ctx.config.mediaSyncLimit || 300;
@@ -140,12 +165,19 @@ export function registerPullCommands(program, resolveContext) {
                 if (res.deleted) {
                     console.log(`🗑️ Remote article was deleted. Pruned local file: ${res.filePath}`);
                 }
+                else if (res.localEditsPreserved) {
+                    console.log(`🛡️ Kept your local edits for ${res.slug} (${res.filePath}); remote changes were NOT applied.`);
+                    console.log(`   Push them with "emit push ${res.filePath}", or re-run with --force to accept the remote version.`);
+                }
                 else if (res.skipped) {
                     console.log(`ℹ️ Article ${res.slug} is already up-to-date (${res.filePath})`);
                 }
                 else {
                     console.log(`✅ Pulled ${res.slug} -> ${res.filePath}`);
                 }
+                const quarantineNotice = formatQuarantineNotice(res.quarantined);
+                if (quarantineNotice)
+                    console.log(`\n${quarantineNotice}`);
             }
         }
         catch (error) {
@@ -153,6 +185,10 @@ export function registerPullCommands(program, resolveContext) {
                 console.error(`\n❌ ${error.message}`);
                 process.exit(1);
             }
+            if (error instanceof ApiError) {
+                console.error(`\n${error.toActionableString()}`);
+                process.exit(1);
+            }
             throw error;
         }
     });
@@ -163,30 +199,42 @@ export function registerPullCommands(program, resolveContext) {
         .option('-p, --profile <name>', 'Explicitly use a specific connection profile')
         .action(async (options) => {
         const ctx = resolveContext(options.profile);
-        console.log('Pulling categories and tags from remote...');
-        const res = await pullTaxonomies({
-            workspaceRoot: ctx.root,
-            origin: ctx.origin,
-            token: ctx.auth.token,
-            refreshToken: ctx.auth.refreshToken,
-        });
-        const prunedCatMsg = res.deletedCategoriesCount
-            ? `, ${res.deletedCategoriesCount} categories pruned`
-            : '';
-        const prunedTagMsg = res.deletedTagsCount ? `, ${res.deletedTagsCount} tags pruned` : '';
-        if (res.categoriesFailed) {
-            console.warn('⚠️  Failed to fetch remote categories: preserved existing local definitions.');
-        }
-        if (res.tagsFailed) {
-            console.warn('⚠️  Failed to fetch remote tags: preserved existing local definitions.');
-        }
-        if (!res.categoriesFailed || !res.tagsFailed) {
-            console.log(`✅ Successfully synced taxonomies: ${res.categoriesCount} categories, ${res.tagsCount} tags${prunedCatMsg}${prunedTagMsg}.`);
+        try {
+            console.log('Pulling categories and tags from remote...');
+            const res = await pullTaxonomies({
+                workspaceRoot: ctx.root,
+                origin: ctx.origin,
+                token: ctx.auth.token,
+                refreshToken: ctx.auth.refreshToken,
+            });
+            const prunedCatMsg = res.deletedCategoriesCount
+                ? `, ${res.deletedCategoriesCount} categories pruned`
+                : '';
+            const prunedTagMsg = res.deletedTagsCount ? `, ${res.deletedTagsCount} tags pruned` : '';
+            if (res.categoriesFailed) {
+                console.warn('⚠️  Failed to fetch remote categories: preserved existing local definitions.');
+            }
+            if (res.tagsFailed) {
+                console.warn('⚠️  Failed to fetch remote tags: preserved existing local definitions.');
+            }
+            if (!res.categoriesFailed || !res.tagsFailed) {
+                console.log(`✅ Successfully synced taxonomies: ${res.categoriesCount} categories, ${res.tagsCount} tags${prunedCatMsg}${prunedTagMsg}.`);
+            }
+            const taxSummary = getLocalTaxonomiesSummary(ctx.root);
+            const taxHint = formatTaxonomiesHint(taxSummary, { maxTags: 60 });
+            if (taxHint) {
+                console.log(`\n${taxHint}`);
+            }
+            if (res.categoriesFailed && res.tagsFailed) {
+                process.exit(1);
+            }
         }
-        const taxSummary = getLocalTaxonomiesSummary(ctx.root);
-        const taxHint = formatTaxonomiesHint(taxSummary, { maxTags: 60 });
-        if (taxHint) {
-            console.log(`\n${taxHint}`);
+        catch (error) {
+            if (error instanceof ApiError) {
+                console.error(`\n${error.toActionableString()}`);
+                process.exit(1);
+            }
+            throw error;
         }
     });
     // emit pull-media
@@ -205,19 +253,28 @@ export function registerPullCommands(program, resolveContext) {
             : options.limit
                 ? parseInt(options.limit, 10)
                 : ctx.config.mediaSyncLimit || 300;
-        console.log(`Pulling media from remote (${options.all ? 'all' : `limit: ${limit}`})...`);
-        const res = await pullMedia({
-            workspaceRoot: ctx.root,
-            origin: ctx.origin,
-            token: ctx.auth.token,
-            refreshToken: ctx.auth.refreshToken,
-            limit,
-            all: options.all,
-            prune: options.prune,
-            downloadFiles: !options.metadataOnly,
-        });
-        const deletedMsg = res.deleted ? `, ${res.deleted} pruned` : '';
-        console.log(`✅ Media sync complete: ${res.total} total items (${res.downloaded} downloaded, ${res.skipped} skipped/up-to-date${deletedMsg}).`);
+        try {
+            console.log(`Pulling media from remote (${options.all ? 'all' : `limit: ${limit}`})...`);
+            const res = await pullMedia({
+                workspaceRoot: ctx.root,
+                origin: ctx.origin,
+                token: ctx.auth.token,
+                refreshToken: ctx.auth.refreshToken,
+                limit,
+                all: options.all,
+                prune: options.prune,
+                downloadFiles: !options.metadataOnly,
+            });
+            const deletedMsg = res.deleted ? `, ${res.deleted} pruned` : '';
+            console.log(`✅ Media sync complete: ${res.total} total items (${res.downloaded} downloaded, ${res.skipped} skipped/up-to-date${deletedMsg}).`);
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                console.error(`\n${error.toActionableString()}`);
+                process.exit(1);
+            }
+            throw error;
+        }
     });
 }
 //# sourceMappingURL=pull.js.map