obris-cli 0.6.2__tar.gz → 0.7.3__tar.gz

{obris_cli-0.6.2 → obris_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: obris-cli
-Version: 0.6.2
+Version: 0.7.3
 Summary: Save, organize, and access your knowledge from the command line
 Project-URL: Homepage, https://obris.ai
 Project-URL: Repository, https://github.com/obris-dev/obris

{obris_cli-0.6.2 → obris_cli-0.7.3}/README.md

@@ -43,6 +43,7 @@ Opens a browser to log in. The CLI waits, you authorize, done. Works from any ma
 | `obris sync [path]` | Sync a directory with an Obris topic |
 | `obris sync add <file>` | Add a local file to a synced topic |
 | `obris sync link <file> -i <id>` | Relink a renamed file |
+| `obris sync unlink <file-or-id>` | Break the local-to-remote sync link |
 | `obris topic list` | List all topics |
 | `obris topic view <id>` | View a topic and its knowledge items |
 | `obris knowledge view <id>` | View a knowledge item |

{obris_cli-0.6.2 → obris_cli-0.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "obris-cli"
-version = "0.6.2"
+version = "0.7.3"
 description = "Save, organize, and access your knowledge from the command line"
 
 requires-python = ">=3.10"

{obris_cli-0.6.2 → obris_cli-0.7.3}/src/obris/commands/sync.py

@@ -7,8 +7,9 @@ from obris.commands.sync_config import register as _register_config_subcommands
 from obris.commands.sync_conflicts import register as _register_conflicts_subgroup
 from obris.output import as_json, is_json
 from obris.sync.commands import add_file, link_file
+from obris.sync.preview import preview_first_sync
 from obris.sync.resolver import assert_all_roots, find_root_id, resolve_targets
-from obris.sync.runner import preview_first_sync, run_sync_pass
+from obris.sync.runner import run_sync_pass
 from obris.sync.state import SyncState
 
 
@@ -68,6 +69,15 @@ def sync(ctx, path, topic_id, item_ids, include_patterns, dry_run, add_all_files
 
     targets = resolve_targets(sync_dir, topic_id, no_create=no_create, dry_run=dry_run)
 
+    if add_all_files and len(targets) > 1:
+        topic_ids = [t[1] for t in targets]
+        raise click.UsageError(
+            "--add-all is ambiguous when multiple topics are linked to this "
+            "directory. Pass --topic <id> to scope it to one topic, or use "
+            "'obris sync add <file> -t <id>' to add files one at a time.\n"
+            f"  Linked topics: {', '.join(topic_ids)}"
+        )
+
     if not targets:
         # dry-run + no state + no --topic: preview the bootstrap +
         # initial-add locally without creating a phantom server topic.
@@ -102,6 +112,7 @@ def sync(ctx, path, topic_id, item_ids, include_patterns, dry_run, add_all_files
                 "symlinks": totals["symlinks"],
                 "conflicts_pending": totals["conflicts_pending"],
                 "missing_local": totals["missing_local"],
+                "skipped_by_include": totals.get("skipped_by_include", []),
             }
         )
 
@@ -213,7 +224,7 @@ def sync_link(file, item_id, topic_id):
     click.echo(f'Linked "{filepath.name}" to item {item_id}')
 
 
-# Per-checkout configuration subcommands (exclude / include / untrack)
+# Per-checkout configuration subcommands (exclude / include / unlink)
 # and the conflicts subgroup live in separate modules to keep this
 # file under the 300-line cap.
 _register_config_subcommands(sync)

obris_cli-0.7.3/src/obris/commands/sync_config.py

@@ -0,0 +1,290 @@
+"""Per-checkout sync configuration subcommands.
+
+Hosts ``exclude`` / ``include`` / ``unlink`` — commands that modify
+state-file metadata for a synced directory. Kept out of
+``commands.sync`` so the sync group definition + invocation logic
+stays under the 300-line cap and these subcommands stay together
+because they share the ``_states_for_current_dir`` resolver.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+import pathspec
+from pathspec.patterns.gitwildmatch import GitWildMatchPattern
+
+from obris.sync.exclusions import ExclusionMatcher
+from obris.sync.state import SyncState
+
+
+def _states_for_current_dir(path):
+    """Return ``(sync_dir, states)`` for ``path``, exiting cleanly if unsynced."""
+    sync_dir = Path(path).resolve()
+    states = SyncState.find_all_for_path(sync_dir)
+    if not states:
+        raise SystemExit(f"No synced topic found for {sync_dir}/. Run 'obris sync --topic <id>' first.")
+    return sync_dir, states
+
+
+def register(sync):
+    """Attach the config subcommands to the given Click group."""
+
+    @sync.command("exclude")
+    @click.argument("patterns", nargs=-1)
+    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
+    @click.option("--list", "list_only", is_flag=True, help="Print current settings")
+    def sync_exclude(patterns, path, list_only):
+        """Stop syncing files that match a pattern.
+
+        \b
+          obris sync exclude scratch/          # an entire folder
+          obris sync exclude notes.draft.md    # a specific file
+          obris sync exclude '*.draft.md'      # all drafts
+          obris sync exclude --list            # show current settings
+
+        Wins over any prior ``obris sync include`` for the same
+        pattern, so the user-facing rule stays simple: "the last
+        thing you said is what happens."
+        """
+        sync_dir, states = _states_for_current_dir(path)
+
+        if list_only:
+            if patterns:
+                raise click.UsageError("Cannot combine --list with patterns.")
+            _list_settings(states)
+            return
+
+        if not patterns:
+            raise click.UsageError("Provide one or more patterns, or use --list.")
+
+        results = _apply_pattern_action(states, patterns, action="exclude", sync_dir=sync_dir)
+        _emit_outcomes(sync_dir, results, action="exclude")
+
+    @sync.command("include")
+    @click.argument("patterns", nargs=-1, required=True)
+    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
+    def sync_include(patterns, path):
+        """Force a file or pattern to sync, overriding any exclusion.
+
+        Use this whenever ``obris sync`` says a file is being skipped
+        and you actually want it. Works whether the file was being
+        excluded by a built-in default or by a prior
+        ``obris sync exclude``.
+
+        \b
+          obris sync include .env.example      # sync this even though
+                                                #  .env.* is excluded by default
+          obris sync include scratch/draft.md  # sync one file inside an
+                                                #  excluded folder
+          obris sync include '*.draft.md'      # un-exclude a pattern you
+                                                #  previously excluded
+
+        Wins over any prior ``obris sync exclude`` for the same pattern
+        — last call wins.
+        """
+        sync_dir, states = _states_for_current_dir(path)
+        results = _apply_pattern_action(states, patterns, action="include", sync_dir=sync_dir)
+        _emit_outcomes(sync_dir, results, action="include")
+
+    @sync.command("unlink")
+    @click.argument("targets", nargs=-1, required=True)
+    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
+    def sync_unlink(targets, path):
+        """Break the local-to-remote sync link without deleting either side.
+
+        Each TARGET is a knowledge ID or a linked filename (basename).
+        Removes the sync link; both the local file and the remote item stay
+        in place. Subsequent 'obris sync' calls will not re-pull these items.
+
+        \b
+          obris sync unlink abc123
+          obris sync unlink notes.md draft.md
+
+        Re-link later with 'obris sync link <file> -i <id>' or 'obris sync add'.
+        Permanently delete the remote with 'obris knowledge delete <id>'.
+        """
+        sync_dir, states = _states_for_current_dir(path)
+
+        unlinked = []
+        not_found = []
+        for target in targets:
+            matches = _resolve_target(target, states)
+            if not matches:
+                not_found.append(target)
+                continue
+            if len(matches) > 1:
+                click.echo(f"Ambiguous: '{target}' matches multiple linked items:")
+                for state, kid in matches:
+                    entry = state.get(kid)
+                    click.echo(f"  {kid}  ({entry.filename})")
+                click.echo("  Re-run with the specific knowledge ID.")
+                raise SystemExit(1)
+            state, kid = matches[0]
+            entry = state.get(kid)
+            state.untrack(kid)
+            state.mark_unlinked(kid)
+            state.save()
+            unlinked.append((kid, entry.filename))
+
+        if unlinked:
+            click.echo(f"Unlinked {len(unlinked)} item(s):")
+            for kid, name in unlinked:
+                click.echo(f"  {name}  ({kid})")
+            click.echo(f"  Local files and remote items unchanged in {sync_dir}/.")
+        if not_found:
+            click.echo(f"Not linked: {', '.join(not_found)}", err=True)
+            raise SystemExit(1)
+
+
+def _apply_pattern_action(states, patterns, *, action, sync_dir):
+    """Apply ``exclude`` or ``include`` to each pattern across all states.
+
+    Returns ``[(pattern, outcome)]`` where outcome is one of
+    ``now_skipped``, ``now_synced``, ``already_skipped``,
+    ``already_synced``, or ``no_effect``.
+
+    Strict inverses with last-call-wins semantics *and* exact-cancel:
+    when the new action's inverse is already in state we simply remove
+    it instead of layering an opposite on top. Net effect per pattern:
+
+    - prior ``foo`` + ``include foo``   → state minus ``foo``
+    - prior ``!foo`` + ``exclude foo``  → state minus ``!foo``
+    - empty + ``include foo``           → state plus ``!foo`` (only if
+                                           the pattern actually matches
+                                           a currently-excluded local
+                                           file; otherwise ``no_effect``
+                                           with no state change)
+    - empty + ``exclude foo``           → state plus ``foo``
+
+    Keeps the state at most one entry per pattern, no leftover
+    re-include or exclude after a toggle, and no state bloat from
+    ``include`` calls that wouldn't have changed anything.
+    """
+    outcomes = []
+    for state, _tid in states:
+        for pat in patterns:
+            negated = f"!{pat}"
+            current = list(state.exclude_patterns)
+            if action == "exclude":
+                if negated in current:
+                    # Cancel a prior include — just remove the override,
+                    # don't also add the exclude. Defaults re-cover the
+                    # path if the override existed to override one; if
+                    # not, both calls were no-ops on observable behavior.
+                    state.remove_excludes([negated])
+                    state.save()
+                    outcomes.append((pat, "now_skipped"))
+                elif pat in current:
+                    outcomes.append((pat, "already_skipped"))
+                else:
+                    state.add_excludes([pat])
+                    state.save()
+                    outcomes.append((pat, "now_skipped"))
+            else:
+                if pat in current:
+                    # Cancel a prior exclude — defaults take over.
+                    state.remove_excludes([pat])
+                    state.save()
+                    outcomes.append((pat, "now_synced"))
+                elif negated in current:
+                    outcomes.append((pat, "already_synced"))
+                elif _include_has_effect(sync_dir, pat, current):
+                    state.add_excludes([negated])
+                    state.save()
+                    outcomes.append((pat, "now_synced"))
+                else:
+                    # No currently-excluded file matches this pattern;
+                    # adding ``!pat`` would be state bloat with zero
+                    # observable effect. Warn and leave state alone.
+                    outcomes.append((pat, "no_effect"))
+    return outcomes
+
+
+def _include_has_effect(sync_dir: Path, pattern: str, current_excludes: list[str]) -> bool:
+    """Return True if any local file currently excluded would match ``pattern``.
+
+    Conservative: only files that physically exist under ``sync_dir``
+    count. A pattern aimed at a file that doesn't exist yet is treated
+    as no-op — the user can re-run after the file lands. Walks
+    ``sync_dir`` once per call; cost is negligible compared to a real
+    sync's network round trips.
+    """
+    matcher = ExclusionMatcher(sync_dir, state_excludes=current_excludes)
+    pattern_spec = pathspec.PathSpec.from_lines(GitWildMatchPattern, [pattern])
+    for path in Path(sync_dir).rglob("*"):
+        if path.is_dir() or path.is_symlink():
+            continue
+        rel = path.relative_to(sync_dir).as_posix()
+        if matcher.excludes(rel) and pattern_spec.match_file(rel):
+            return True
+    return False
+
+
+def _emit_outcomes(sync_dir, results, *, action):
+    """User-facing summary. No mention of state mechanics or `!pattern`."""
+    by_outcome: dict[str, set[str]] = {}
+    for pat, outcome in results:
+        by_outcome.setdefault(outcome, set()).add(pat)
+
+    changed_any = False
+    if action == "exclude":
+        if by_outcome.get("now_skipped"):
+            click.echo(f"Skipping: {', '.join(sorted(by_outcome['now_skipped']))}")
+            changed_any = True
+        if by_outcome.get("already_skipped"):
+            click.echo(f"Already skipping: {', '.join(sorted(by_outcome['already_skipped']))}")
+    else:
+        if by_outcome.get("now_synced"):
+            click.echo(f"Now syncing: {', '.join(sorted(by_outcome['now_synced']))}")
+            changed_any = True
+        if by_outcome.get("already_synced"):
+            click.echo(f"Already syncing: {', '.join(sorted(by_outcome['already_synced']))}")
+        if by_outcome.get("no_effect"):
+            pats = sorted(by_outcome["no_effect"])
+            click.echo(f"No matching skipped file(s) for: {', '.join(pats)}", err=True)
+            click.echo("  Nothing to include. Run again after the file appears, or check spelling.")
+
+    if changed_any:
+        click.echo(f"  Takes effect on next 'obris sync' in {sync_dir}/.")
+
+
+def _list_settings(states):
+    """Print currently-configured rules for each state, grouped by intent."""
+    for state, tid in states:
+        current = state.exclude_patterns
+        header = f"Settings for {tid}:" if len(states) > 1 else "Current settings:"
+        click.echo(header)
+        if not current:
+            click.echo("  (none — built-in defaults apply)")
+            continue
+        skips = [p for p in current if not p.startswith("!")]
+        forced_syncs = [p[1:] for p in current if p.startswith("!")]
+        if skips:
+            click.echo("  Skipping:")
+            for p in skips:
+                click.echo(f"    {p}")
+        if forced_syncs:
+            click.echo("  Always syncing:")
+            for p in forced_syncs:
+                click.echo(f"    {p}")
+
+
+def _resolve_target(target, states):
+    """Resolve ``target`` (kid or filename) to a list of (state, kid) matches.
+
+    Filename lookup is by basename only (matches TrackedItem.filename).
+    Returns a list because the same filename can exist under different
+    topics in the same dir; the caller decides whether to error on
+    ambiguity.
+    """
+    matches = []
+    for state, _tid in states:
+        if state.is_tracked(target):
+            matches.append((state, target))
+            continue
+        kid, _entry = state.find_by_filename(target)
+        if kid:
+            matches.append((state, kid))
+    return matches

{obris_cli-0.6.2 → obris_cli-0.7.3}/src/obris/sync/engine/run.py

@@ -128,7 +128,7 @@ def run_sync(
             continue
         seen_ids.add(item.id)
         if state.is_unlinked(item.id):
-            # User ran 'obris sync untrack' on this id. Leave the
+            # User ran 'obris sync unlink' on this id. Leave the
             # remote alone, don't pull, don't surface — they
             # explicitly opted out of syncing this item.
             continue
@@ -143,9 +143,15 @@ def run_sync(
         if filter_item_ids and item.id not in filter_item_ids:
             continue
 
+        # On a dry-run pass, ``reconcile_topic_dirs`` deliberately doesn't
+        # call ``state.set_topic_dir`` (no side effects on the local state
+        # file), so ``state.get_topic_dir`` returns None for any subtopic
+        # that the live run would create. Fall back to the desired map
+        # the manifest already gave us, otherwise dry-run output prints
+        # bare basenames with no parent directory context.
         item_rel = state.get_topic_dir(item.topic_id) if item.topic_id else ""
         if item_rel is None:
-            item_rel = ""
+            item_rel = desired_topic_dirs.get(item.topic_id, "") if item.topic_id else ""
 
         if state.is_tracked(item.id):
             entry = state.get(item.id)

{obris_cli-0.6.2 → obris_cli-0.7.3}/src/obris/sync/engine/tracked.py

@@ -78,7 +78,7 @@ def sync_tracked_item(topic_id, item, entry, state, sync_dir, desired_rel, *, dr
         click.echo(f"  Missing locally: {display}  (knowledge_id {item.id})")
         click.echo("    Options:")
         click.echo(f"      obris sync link <new-path> -i {item.id}    # moved or renamed")
-        click.echo(f"      obris sync untrack {item.id}               # keep both copies, stop syncing")
+        click.echo(f"      obris sync unlink {item.id}                 # keep both copies, break the link")
         click.echo(f"      obris knowledge delete {item.id}           # remove the remote item")
         return MISSING
 

{obris_cli-0.6.2 → obris_cli-0.7.3}/src/obris/sync/exclusions.py

@@ -1,17 +1,19 @@
 """File-level exclusion matcher for sync.
 
-Combines three pattern sources, all gitignore-style (``pathspec``'s
-``gitwildmatch``):
-
-1. **Built-in defaults** — always applied, hardcoded in this module.
-   Hides VCS metadata, dependency dirs, OS / editor cruft.
-2. **``.obrisignore``** — user-authored, lives at the sync-dir root.
-   The CLI reads it; it never writes to it.
-3. **State-level excludes** — per-checkout, set via
-   ``obris sync exclude``. Plumbed through ``state_excludes`` so this
-   module has no opinion on where they're persisted.
-
-Supports gitignore semantics including ``!pattern`` re-includes.
+Combines two pattern sources, evaluated in order, gitignore-style
+(``pathspec``'s ``gitwildmatch``):
+
+1. **Built-in defaults** — hardcoded in this module. Hides VCS
+   metadata, dependency dirs, OS / editor cruft, and credential-shaped
+   files.
+2. **State-level rules** — set via ``obris sync exclude`` and
+   ``obris sync include``. Stored as a list of patterns on each
+   ``SyncState``; ``!pattern`` entries are re-includes that override
+   the defaults. The CLI is the only writer.
+
+Last match wins (gitignore semantics), so state-level rules can
+always override defaults. Users never hand-edit a config file —
+state is owned by the CLI.
 """
 
 from __future__ import annotations
@@ -22,6 +24,11 @@ import pathspec
 from pathspec.patterns.gitwildmatch import GitWildMatchPattern
 
 DEFAULT_EXCLUDES = [
+    # Obris's own in-dir state. Lives at ``<sync_dir>/.obris/`` and is
+    # never knowledge content. Self-excludes to avoid an infinite-loop
+    # of "the engine sees state files, would push them, server stores
+    # them, sync sees the new items..."
+    ".obris/",
     # VCS
     ".git/",
     ".hg/",
@@ -51,21 +58,22 @@ DEFAULT_EXCLUDES = [
     # Temp
     "*.tmp",
     "*.bak",
+    # Secrets — common files / dirs that hold credentials. Kept narrow
+    # to literal known-bad paths instead of a blanket dotfile rule so
+    # AI-tool config dirs (.claude/, .cursor/, .github/, etc.) keep
+    # syncing. Users can override any default with
+    # ``obris sync include <pattern>``.
+    ".env",
+    ".env.*",
+    ".envrc",
+    ".netrc",
+    ".npmrc",
+    ".pypirc",
+    ".aws/",
+    ".gnupg/",
+    ".ssh/",
 ]
 
-OBRISIGNORE = ".obrisignore"
-
-
-def _read_obrisignore(sync_dir: Path) -> list[str]:
-    path = sync_dir / OBRISIGNORE
-    if not path.exists():
-        return []
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return []
-    return [line for line in lines if line.strip() and not line.strip().startswith("#")]
-
 
 class ExclusionMatcher:
     """Single matcher built once per sync pass, queried per file.
@@ -80,8 +88,6 @@ class ExclusionMatcher:
         self._sources: list[tuple[str, str]] = []
         for pat in DEFAULT_EXCLUDES:
             self._sources.append(("default", pat))
-        for pat in _read_obrisignore(self.sync_dir):
-            self._sources.append((OBRISIGNORE, pat))
         for pat in state_excludes or []:
             self._sources.append(("state", pat))
         self._spec = pathspec.PathSpec.from_lines(GitWildMatchPattern, [pat for _, pat in self._sources])
@@ -94,8 +100,8 @@ class ExclusionMatcher:
         """Return ``[(source_label, pattern), ...]`` for every pattern that matches.
 
         A path can match multiple patterns; this returns all of them in
-        source order (defaults → .obrisignore → state). Used for
-        diagnostics, not for the actual exclude decision.
+        source order (defaults → state). Used for diagnostics, not
+        for the actual exclude decision.
         """
         matched = []
         for label, pat in self._sources:

obris_cli-0.7.3/src/obris/sync/preview.py

@@ -0,0 +1,109 @@
+"""Local-only dry-run preview for first-time syncs.
+
+Used when the user runs ``obris sync --dry-run`` against a directory
+that has no linked topic yet — ``resolve_targets`` returns an empty
+target list rather than creating a phantom topic on the server, and
+the sync command falls through to this preview helper instead of
+the regular ``run_sync_pass``.
+
+Side-effect free: walks the dir using a synthetic ``SyncState`` so
+the same exclusion + symlink + tracked-name logic runs as on a real
+sync. Reports what ``create_topic``, ``_ensure_subtopic_path``, and
+``add_all`` *would* do without touching the server.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+import click
+
+from obris.sync.scanner import find_untracked
+from obris.sync.state import SyncState
+
+
+def preview_first_sync(sync_dir: Path, *, add_all_files: bool, allow_subtopics: bool) -> dict:
+    """Render a local-only preview of what a first sync would create.
+
+    Output sections (each only emitted when non-empty):
+
+    - the would-be root topic name
+    - the subtopic structure that would be mirrored from local subdirs
+    - untracked files (gated on ``--add-all`` and ``--no-subtopics``)
+    - ignored files (always shown — user explicitly asked for the full picture)
+    - symlinks (always shown)
+
+    Returns the same totals dict shape as ``run_sync_pass`` so the
+    JSON output stays consistent across both code paths.
+    """
+    sync_dir = Path(sync_dir).resolve()
+    topic_name = sync_dir.name
+    click.echo("  (dry run — no changes will be made)")
+    click.echo(f'  Would create topic "{topic_name}" at {sync_dir}/')
+
+    synthetic = SyncState("__preview__", str(sync_dir))
+    scan = find_untracked(sync_dir, [(synthetic, "__preview__")])
+
+    # Subtopic projection: every directory segment under sync_dir that
+    # contains an untracked file would become a subtopic level. Mirrors
+    # the cache walk in ``scanner._ensure_subtopic_path``.
+    subdirs: set[str] = set()
+    skipped_subdir = 0
+    if allow_subtopics:
+        for rel in scan.untracked:
+            rel_dir = str(PurePosixPath(rel).parent)
+            if rel_dir == ".":
+                continue
+            walked = ""
+            for seg in rel_dir.split("/"):
+                walked = f"{walked}/{seg}" if walked else seg
+                subdirs.add(walked)
+    else:
+        skipped_subdir = sum(1 for rel in scan.untracked if "/" in rel)
+
+    if subdirs:
+        click.echo(f"\nWould create {len(subdirs)} subtopic(s):")
+        for sd in sorted(subdirs):
+            click.echo(f"  {sd}/")
+
+    if scan.untracked:
+        if not add_all_files:
+            click.echo(f"\n{len(scan.untracked)} untracked file(s) (would NOT add — re-run with --add-all):")
+            _print_all(scan.untracked)
+        elif not allow_subtopics:
+            top_level = [r for r in scan.untracked if "/" not in r]
+            click.echo(f"\nWould add {len(top_level)} top-level file(s):")
+            _print_all(top_level)
+            if skipped_subdir:
+                click.echo(f"\nWould skip {skipped_subdir} file(s) in subdirs (--no-subtopics):")
+                _print_all([r for r in scan.untracked if "/" in r])
+        else:
+            click.echo(f"\nWould add {len(scan.untracked)} file(s):")
+            _print_all(scan.untracked)
+
+    if scan.excluded:
+        click.echo(f"\n{len(scan.excluded)} file(s) matched ignore rules:")
+        _print_all(scan.excluded)
+
+    if scan.symlinks:
+        click.echo(f"\n{len(scan.symlinks)} symlink(s) skipped:")
+        _print_all([f"{p} -> {t}" for p, t in scan.symlinks])
+
+    return {
+        "pulled": 0,
+        "pushed": 0,
+        "conflicts": 0,
+        "errors": 0,
+        "untracked": list(scan.untracked),
+        "excluded_count": len(scan.excluded),
+        "symlinks": [{"path": p, "target": t} for p, t in scan.symlinks],
+        "conflicts_pending": [],
+        "missing_local": [],
+        "skipped_by_include": [],
+    }
+
+
+def _print_all(items):
+    """Print every item, one per line, indented."""
+    for line in items:
+        click.echo(f"  {line}")

{obris_cli-0.6.2 → obris_cli-0.7.3}/src/obris/sync/runner.py

@@ -8,6 +8,7 @@ import click
 
 from obris.api.topics import get_topic
 from obris.sync.engine import run_sync
+from obris.sync.engine.filters import any_match
 from obris.sync.resolver import find_root
 from obris.sync.scanner import add_all, find_untracked
 from obris.sync.state import SyncState
@@ -47,6 +48,7 @@ def run_sync_pass(
         "symlinks": [],
         "conflicts_pending": [],
         "missing_local": [],
+        "skipped_by_include": [],
     }
 
     if dry_run:
@@ -98,9 +100,23 @@ def run_sync_pass(
     if not fresh_states:
         return totals
     scan = find_untracked(sync_dir, fresh_states)
+
+    # When --add-all is combined with --include, the bulk-add should
+    # honor the same scope the rest of the sync uses — pull, push,
+    # tracked-item dispatch, remote-deleted detection all already
+    # respect ``patterns``. ``find_untracked`` doesn't see the patterns,
+    # so we partition its result here. Files outside the include scope
+    # are surfaced separately so the user knows they were skipped on
+    # purpose, not silently dropped.
+    out_of_include_scope: list[str] = []
+    if add_all_files and patterns and scan.untracked:
+        in_scope, out_of_include_scope = _partition_by_include(scan.untracked, patterns)
+        scan.untracked = in_scope
+
     totals["untracked"] = list(scan.untracked)
     totals["excluded_count"] = len(scan.excluded)
     totals["symlinks"] = [{"path": p, "target": t} for p, t in scan.symlinks]
+    totals["skipped_by_include"] = list(out_of_include_scope)
     for state, _tid in fresh_states:
         for kid, meta in state.conflicts.items():
             entry = state.get(kid)
@@ -115,16 +131,22 @@ def run_sync_pass(
                     "remote_updated_at": meta.get("remote_updated_at"),
                 }
             )
-    _emit_scan(scan, sync_dir, add_all_files, verbose=verbose)
+    _emit_scan(scan, sync_dir, add_all_files, dry_run=dry_run, verbose=verbose)
+
+    if out_of_include_scope:
+        cap = None if verbose else _LIST_PREVIEW
+        click.echo(f"\nSkipped {len(out_of_include_scope)} untracked file(s) outside --include scope:")
+        _print_capped(out_of_include_scope, cap)
 
     if add_all_files and scan.untracked and not dry_run:
-        # All targets share the same sync_dir; bulk-add against the
-        # first state's root. Multi-root dirs are an edge case we
-        # don't optimize for here.
-        first_state, root_id = fresh_states[0]
+        # Bulk-add into the resolved target. The CLI rejects --add-all
+        # in multi-topic directories without an explicit --topic, so by
+        # the time we get here ``targets`` has exactly one entry.
+        target_tid = targets[0][1]
+        target_state = next(s for s, tid in fresh_states if tid == target_tid)
         counts = add_all(
-            first_state,
-            root_id,
+            target_state,
+            target_tid,
             sync_dir,
             scan.untracked,
             allow_subtopics=allow_subtopics,
@@ -141,14 +163,29 @@ def run_sync_pass(
     return totals
 
 
-def _emit_scan(scan, sync_dir, add_all_files, *, verbose=False):
+def _emit_scan(scan, sync_dir, add_all_files, *, dry_run=False, verbose=False):
     if not scan.untracked and not scan.symlinks and not (verbose and scan.excluded):
         return
     cap = None if verbose else _LIST_PREVIEW
     if scan.untracked:
-        click.echo(f"\n{len(scan.untracked)} untracked file(s) in {sync_dir}/:")
-        _print_capped(scan.untracked, cap)
-        if not add_all_files:
+        # Output is shaped by the (dry_run, add_all_files) combination so
+        # the user always knows whether the listed files would actually
+        # be uploaded:
+        #   dry-run + --add-all  → preview header ("Would add ...")
+        #   dry-run, no --add-all → preview header ("would not add")
+        #   live    + --add-all  → silent here (the real add path prints
+        #                          its own "Added N file(s)" summary)
+        #   live, no --add-all   → the existing "Choose how to proceed"
+        #                          prompt with the add/skip recipes.
+        if dry_run and add_all_files:
+            click.echo(f"\nWould add {len(scan.untracked)} file(s):")
+            _print_capped(scan.untracked, cap)
+        elif dry_run:
+            click.echo(f"\n{len(scan.untracked)} untracked file(s) (would not add — re-run with --add-all):")
+            _print_capped(scan.untracked, cap)
+        elif not add_all_files:
+            click.echo(f"\n{len(scan.untracked)} untracked file(s) in {sync_dir}/:")
+            _print_capped(scan.untracked, cap)
             click.echo("  Choose how to proceed:")
             click.echo("    Upload all:   obris sync --add-all")
             click.echo("    Upload some:  obris sync add <file>...")
@@ -161,6 +198,29 @@ def _emit_scan(scan, sync_dir, add_all_files, *, verbose=False):
         _print_capped(scan.excluded, cap)
 
 
+def _partition_by_include(rels: list[str], patterns: list[str]) -> tuple[list[str], list[str]]:
+    """Split untracked rel-paths by whether their parent dir is in --include scope.
+
+    A file's parent directory becomes (or maps to) a subtopic name path
+    when ``--add-all`` runs; we test the same name path against the
+    patterns the engine already evaluates against the remote subtree.
+    Root-level files (parent is ``"."``) test against an empty segment
+    list — patterns like ``Projects/**`` won't match, which mirrors
+    the engine's own behaviour where the root topic isn't in
+    ``matched_ids`` when patterns are set.
+    """
+    in_scope: list[str] = []
+    out_of_scope: list[str] = []
+    for rel in rels:
+        rel_dir = str(PurePosixPath(rel).parent)
+        segments = [] if rel_dir == "." else [s for s in rel_dir.split("/") if s]
+        if any_match(segments, patterns):
+            in_scope.append(rel)
+        else:
+            out_of_scope.append(rel)
+    return in_scope, out_of_scope
+
+
 def _print_capped(items, cap):
     """Print at most ``cap`` items, then a "... N more" line. None = no cap."""
     shown = items if cap is None else items[:cap]
@@ -168,84 +228,3 @@ def _print_capped(items, cap):
         click.echo(f"  {line}")
     if cap is not None and len(items) > cap:
         click.echo(f"  ... ({len(items) - cap} more)")
-
-
-def preview_first_sync(sync_dir: Path, *, add_all_files: bool, allow_subtopics: bool) -> dict:
-    """Local-only dry-run preview for a fresh directory.
-
-    Called when ``resolve_targets`` returned ``[]`` (dry-run + no
-    state + no ``--topic``). Side-effect free: walks the dir using a
-    synthetic empty ``SyncState`` so ``find_untracked`` reuses the
-    same exclusion + symlink logic the live path uses, then prints
-    what create_topic / _ensure_subtopic_path / add_all would do.
-
-    Ignored files are surfaced unconditionally — the user explicitly
-    asked for the full picture before committing to a real sync.
-
-    Returns the same totals dict shape as ``run_sync_pass`` so the
-    JSON output stays consistent.
-    """
-    sync_dir = Path(sync_dir).resolve()
-    topic_name = sync_dir.name
-    click.echo("  (dry run — no changes will be made)")
-    click.echo(f'  Would create topic "{topic_name}" at {sync_dir}/')
-
-    synthetic = SyncState("__preview__", str(sync_dir))
-    scan = find_untracked(sync_dir, [(synthetic, "__preview__")])
-
-    # Subtopic projection: every directory segment under sync_dir that
-    # contains an untracked file would become a subtopic level. Mirrors
-    # the cache walk in ``scanner._ensure_subtopic_path``.
-    subdirs: set[str] = set()
-    skipped_subdir = 0
-    if allow_subtopics:
-        for rel in scan.untracked:
-            rel_dir = str(PurePosixPath(rel).parent)
-            if rel_dir == ".":
-                continue
-            walked = ""
-            for seg in rel_dir.split("/"):
-                walked = f"{walked}/{seg}" if walked else seg
-                subdirs.add(walked)
-    else:
-        skipped_subdir = sum(1 for rel in scan.untracked if "/" in rel)
-
-    if subdirs:
-        click.echo(f"\nWould create {len(subdirs)} subtopic(s):")
-        for sd in sorted(subdirs):
-            click.echo(f"  {sd}/")
-
-    if scan.untracked:
-        if not add_all_files:
-            click.echo(f"\n{len(scan.untracked)} untracked file(s) (would NOT add — re-run with --add-all):")
-            _print_capped(scan.untracked, None)
-        elif not allow_subtopics:
-            top_level = [r for r in scan.untracked if "/" not in r]
-            click.echo(f"\nWould add {len(top_level)} top-level file(s):")
-            _print_capped(top_level, None)
-            if skipped_subdir:
-                click.echo(f"\nWould skip {skipped_subdir} file(s) in subdirs (--no-subtopics):")
-                _print_capped([r for r in scan.untracked if "/" in r], None)
-        else:
-            click.echo(f"\nWould add {len(scan.untracked)} file(s):")
-            _print_capped(scan.untracked, None)
-
-    if scan.excluded:
-        click.echo(f"\n{len(scan.excluded)} file(s) matched ignore rules:")
-        _print_capped(scan.excluded, None)
-
-    if scan.symlinks:
-        click.echo(f"\n{len(scan.symlinks)} symlink(s) skipped:")
-        _print_capped([f"{p} -> {t}" for p, t in scan.symlinks], None)
-
-    return {
-        "pulled": 0,
-        "pushed": 0,
-        "conflicts": 0,
-        "errors": 0,
-        "untracked": list(scan.untracked),
-        "excluded_count": len(scan.excluded),
-        "symlinks": [{"path": p, "target": t} for p, t in scan.symlinks],
-        "conflicts_pending": [],
-        "missing_local": [],
-    }

{obris_cli-0.6.2 → obris_cli-0.7.3}/src/obris/sync/state.py

@@ -1,8 +1,14 @@
 """Sync state persistence and manipulation.
 
-State is stored under ~/.obris/sync/, one file per (root topic, local path).
-State is keyed by knowledge_id (the remote item's primary key), not by
-filename. Renames on either side are metadata updates, not create+delete.
+State is stored in-place: ``<sync_dir>/.obris/<topic_id>.json``, one
+file per root topic. When the user deletes the sync dir, state goes
+with it — clean lifecycle, no orphaned global state, no cross-machine
+collisions when two laptops happen to share a path. Mirrors git's
+``.git/`` pattern.
+
+State is keyed by knowledge_id (the remote item's primary key), not
+by filename. Renames on either side are metadata updates, not
+create+delete.
 
 Subtopic support: one state file per *root* topic covers the entire
 subtree. topic_dirs maps topic_id -> relative directory (POSIX-style)
@@ -10,26 +16,39 @@ under local_path. The CLI only syncs root topics (parent_id = NULL);
 child topics are not valid sync targets on their own.
 """
 
-import hashlib
 import json
 from pathlib import Path
 
-from obris.config import CONFIG_DIR
-
 from .mapping import now_iso
 from .models import TrackedItem
 
-SYNC_DIR = CONFIG_DIR / "sync"
+# In-dir state directory name. Excluded by ``DEFAULT_EXCLUDES`` so the
+# engine never tries to sync state files as knowledge.
+STATE_DIR_NAME = ".obris"
+
+
+def _state_dir(local_path) -> Path:
+    return Path(local_path).resolve() / STATE_DIR_NAME
+
 
+def _state_path(topic_id, local_path) -> Path:
+    return _state_dir(local_path) / f"{topic_id}.json"
 
-def _state_key(topic_id, local_path):
-    """Deterministic short hash for a (topic_id, local_path) pair."""
-    raw = f"{topic_id}:{Path(local_path).resolve()}"
-    return hashlib.sha256(raw.encode()).hexdigest()[:16]
 
+def _ensure_state_dir(local_path) -> Path:
+    """Create ``<sync_dir>/.obris/`` and seed a self-excluding ``.gitignore``.
 
-def _state_path(topic_id, local_path):
-    return SYNC_DIR / f"{_state_key(topic_id, local_path)}.json"
+    The ``*`` line keeps the state dir out of git/svn checkouts of
+    the user's project — same trick git uses for ``.git/info``.
+    Idempotent: ``mkdir(parents=True, exist_ok=True)`` and we only
+    write the gitignore when missing.
+    """
+    state_dir = _state_dir(local_path)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    gitignore = state_dir / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n")
+    return state_dir
 
 
 def _read(path):
@@ -74,21 +93,24 @@ class SyncState:
     def find_all_for_path(cls, local_path):
         """Find all states for the given local path.
 
-        Returns list of (SyncState, topic_id) tuples.
+        Walks ``<local_path>/.obris/*.json``. Returns ``[]`` when the
+        state dir doesn't exist yet (fresh, never-synced directory).
         """
-        resolved = str(Path(local_path).resolve())
-        if not SYNC_DIR.exists():
+        resolved = Path(local_path).resolve()
+        state_dir = resolved / STATE_DIR_NAME
+        if not state_dir.exists():
             return []
         results = []
-        for f in SYNC_DIR.glob("*.json"):
+        for f in sorted(state_dir.glob("*.json")):
             data = _read(f)
-            if data and data.get("local_path") == resolved:
-                topic_id = data.get("topic_id")
-                results.append((cls(topic_id, local_path, data), topic_id))
+            if not data:
+                continue
+            topic_id = data.get("topic_id") or f.stem
+            results.append((cls(topic_id, local_path, data), topic_id))
         return results
 
     def save(self):
-        SYNC_DIR.mkdir(parents=True, exist_ok=True)
+        _ensure_state_dir(self.local_path)
         path = _state_path(self.topic_id, self.local_path)
         tmp = path.with_suffix(".tmp")
         data = {
@@ -215,7 +237,7 @@ class SyncState:
     def mark_unlinked(self, knowledge_id):
         """Record that ``knowledge_id`` should not be auto-re-pulled.
 
-        Used by ``obris sync untrack`` so subsequent syncs don't yank
+        Used by ``obris sync unlink`` so subsequent syncs don't yank
         the remote copy back down. Cleared automatically by ``track``.
         """
         if knowledge_id and knowledge_id not in self._unlinked_ids:

{obris_cli-0.6.2 → obris_cli-0.7.3}/uv.lock

@@ -141,7 +141,7 @@ wheels = [
 
 [[package]]
 name = "obris-cli"
-version = "0.6.2"
+version = "0.7.3"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

obris_cli-0.6.2/src/obris/commands/sync_config.py

@@ -1,178 +0,0 @@
-"""Per-checkout sync configuration subcommands.
-
-Hosts ``exclude`` / ``include`` / ``untrack`` — commands that modify
-state-file metadata for a synced directory. Kept out of
-``commands.sync`` so the sync group definition + invocation logic
-stays under the 300-line cap and these subcommands stay together
-because they share the ``_states_for_current_dir`` resolver.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import click
-
-from obris.sync.state import SyncState
-
-
-def _states_for_current_dir(path):
-    """Return ``(sync_dir, states)`` for ``path``, exiting cleanly if unsynced."""
-    sync_dir = Path(path).resolve()
-    states = SyncState.find_all_for_path(sync_dir)
-    if not states:
-        raise SystemExit(f"No synced topic found for {sync_dir}/. Run 'obris sync --topic <id>' first.")
-    return sync_dir, states
-
-
-def register(sync):
-    """Attach the config subcommands to the given Click group."""
-
-    @sync.command("exclude")
-    @click.argument("patterns", nargs=-1)
-    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
-    @click.option("--list", "list_only", is_flag=True, help="Print current exclude patterns and exit")
-    def sync_exclude(patterns, path, list_only):
-        """Add file patterns to skip during sync.
-
-        Patterns use gitignore-style syntax. Examples:
-
-        \b
-          obris sync exclude '*.draft.md'      # any markdown draft
-          obris sync exclude scratch/          # entire directory
-          obris sync exclude notes/private.md  # specific file
-          obris sync exclude --list            # show current patterns
-
-        Patterns apply to all topics syncing this directory. Idempotent —
-        adding a pattern twice is a no-op. Remove patterns with
-        'obris sync include <pattern>'.
-        """
-        sync_dir, states = _states_for_current_dir(path)
-
-        if list_only:
-            if patterns:
-                raise click.UsageError("Cannot combine --list with patterns.")
-            for state, tid in states:
-                current = state.exclude_patterns
-                header = f"Excludes for {tid}:" if len(states) > 1 else "Current excludes:"
-                click.echo(header)
-                if not current:
-                    click.echo("  (none)")
-                else:
-                    for p in current:
-                        click.echo(f"  {p}")
-            return
-
-        if not patterns:
-            raise click.UsageError("Provide one or more patterns, or use --list.")
-
-        added_total = []
-        for state, _tid in states:
-            added = state.add_excludes(patterns)
-            if added:
-                state.save()
-                added_total.extend(added)
-
-        unique_added = sorted(set(added_total))
-        skipped = sorted(set(patterns) - set(unique_added))
-        if unique_added:
-            click.echo(f"Added {len(unique_added)} pattern(s): {', '.join(unique_added)}")
-            click.echo(f"  Excludes apply on next 'obris sync' in {sync_dir}/.")
-        if skipped:
-            click.echo(f"Already present: {', '.join(skipped)}")
-
-    @sync.command("include")
-    @click.argument("patterns", nargs=-1, required=True)
-    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
-    def sync_include(patterns, path):
-        """Remove file patterns from the exclude list (re-enable syncing).
-
-        Inverse of 'obris sync exclude'. Idempotent — removing a pattern
-        that isn't present is a no-op with a notice.
-
-          obris sync include '*.draft.md'
-        """
-        sync_dir, states = _states_for_current_dir(path)
-
-        removed_total = []
-        for state, _tid in states:
-            removed = state.remove_excludes(patterns)
-            if removed:
-                state.save()
-                removed_total.extend(removed)
-
-        unique_removed = sorted(set(removed_total))
-        not_present = sorted(set(patterns) - set(unique_removed))
-        if unique_removed:
-            click.echo(f"Removed {len(unique_removed)} pattern(s): {', '.join(unique_removed)}")
-            click.echo(f"  Will sync on next 'obris sync' in {sync_dir}/.")
-        if not_present:
-            click.echo(f"Not in exclude list: {', '.join(not_present)}")
-
-    @sync.command("untrack")
-    @click.argument("targets", nargs=-1, required=True)
-    @click.option("--path", "-p", default=".", help="Sync directory (defaults to current directory)")
-    def sync_untrack(targets, path):
-        """Stop syncing items without deleting either side.
-
-        Each TARGET is a knowledge ID or a tracked filename (basename).
-        Removes the sync link; both the local file and the remote item stay
-        in place. Subsequent 'obris sync' calls will not re-pull these items.
-
-        \b
-          obris sync untrack abc123
-          obris sync untrack notes.md draft.md
-
-        Re-link later with 'obris sync link <file> -i <id>' or 'obris sync add'.
-        Permanently delete the remote with 'obris knowledge delete <id>'.
-        """
-        sync_dir, states = _states_for_current_dir(path)
-
-        untracked = []
-        not_found = []
-        for target in targets:
-            matches = _resolve_target(target, states)
-            if not matches:
-                not_found.append(target)
-                continue
-            if len(matches) > 1:
-                click.echo(f"Ambiguous: '{target}' matches multiple tracked items:")
-                for state, kid in matches:
-                    entry = state.get(kid)
-                    click.echo(f"  {kid}  ({entry.filename})")
-                click.echo("  Re-run with the specific knowledge ID.")
-                raise SystemExit(1)
-            state, kid = matches[0]
-            entry = state.get(kid)
-            state.untrack(kid)
-            state.mark_unlinked(kid)
-            state.save()
-            untracked.append((kid, entry.filename))
-
-        if untracked:
-            click.echo(f"Untracked {len(untracked)} item(s):")
-            for kid, name in untracked:
-                click.echo(f"  {name}  ({kid})")
-            click.echo(f"  Local files and remote items unchanged in {sync_dir}/.")
-        if not_found:
-            click.echo(f"Not tracked: {', '.join(not_found)}", err=True)
-            raise SystemExit(1)
-
-
-def _resolve_target(target, states):
-    """Resolve ``target`` (kid or filename) to a list of (state, kid) matches.
-
-    Filename lookup is by basename only (matches TrackedItem.filename).
-    Returns a list because the same filename can exist under different
-    topics in the same dir; the caller decides whether to error on
-    ambiguity.
-    """
-    matches = []
-    for state, _tid in states:
-        if state.is_tracked(target):
-            matches.append((state, target))
-            continue
-        kid, _entry = state.find_by_filename(target)
-        if kid:
-            matches.append((state, kid))
-    return matches