vecshift 0.1.0__tar.gz → 0.2.0__tar.gz

{vecshift-0.1.0 → vecshift-0.2.0}/.github/workflows/ci.yml

@@ -25,10 +25,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - run: uv sync --locked
       - run: uv run ruff check .
       - run: uv run ruff format --check .
@@ -45,10 +45,10 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - run: uv sync --locked
       - run: uv run pytest --cov=vecshift --cov-report=term-missing
 
@@ -78,10 +78,10 @@ jobs:
     env:
       VECSHIFT_TEST_PG_DSN: postgresql://postgres:postgres@localhost:5432/postgres
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - run: uv sync --locked
       - run: uv run pytest tests/integration
 
@@ -90,10 +90,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - name: Known vulnerabilities in locked dependencies
         run: |
           uv export --frozen --all-extras --all-groups --no-hashes --no-emit-project -o requirements-audit.txt
@@ -106,10 +106,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
       - run: uv build
       - name: PyPI metadata and README render
         run: uvx twine==7.0.0 check --strict dist/*
@@ -129,7 +129,7 @@ jobs:
       PYTHON_IMAGE: mirror.gcr.io/library/python:3.13-slim@sha256:70729b46c69b4f1e97c4822c1af3df53a1476cf5ddc6c087c0c10bc3a5678c2f
       PGVECTOR_IMAGE: mirror.gcr.io/pgvector/pgvector:pg17@sha256:ac08538c6f8b9904c33c8224c5e5706dbe760aca29db1d096972b4052c22a75d
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Run the offline demo end to end

{vecshift-0.1.0 → vecshift-0.2.0}/.github/workflows/release.yml

@@ -23,10 +23,10 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           # A release never restores a cache that another workflow could have written.
           enable-cache: false
@@ -47,7 +47,7 @@ jobs:
       - name: CHANGELOG.md has notes for this version
         run: python scripts/release_notes.py "$GITHUB_REF_NAME" > /dev/null
       - run: uvx twine==7.0.0 check --strict dist/*
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: dist
           path: dist/
@@ -66,7 +66,7 @@ jobs:
     permissions:
       id-token: write # trusted publishing to PyPI
     steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: dist
           path: dist/
@@ -83,10 +83,10 @@ jobs:
       id-token: write # sign the provenance attestation
       attestations: write # store it
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: docker/setup-qemu-action@1f40c72289eff860ee54a304f1438e3cff362e0a # v4.3.0
+      - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
       - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
       - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
@@ -127,10 +127,10 @@ jobs:
     permissions:
       contents: write # create the release
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: dist
           path: dist/

{vecshift-0.1.0 → vecshift-0.2.0}/CHANGELOG.md

@@ -7,7 +7,20 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.1.0]
+## [0.2.0] - 2026-10-10
+
+### Added
+
+- `vecshift init` guides you at a terminal: it asks for the connection string (hidden),
+  lists the vector columns it finds, picks the text column, and offers a short list of
+  models and a spending limit, then shows the plan. Flags still work without prompts.
+- Commands read settings such as `VECSHIFT_DSN` and `OPENAI_API_KEY` from a `.env` file in
+  the current folder. Variables already set take precedence; `--env-file` and
+  `--no-env-file` choose another file or none. `init` can save to it, privately.
+- `vecshift status` shows where a migration stands and what to run next (`--json` too).
+- Running `vecshift` alone, and `vecshift init`, show the logo at a colour terminal.
+
+## [0.1.0] - 2026-10-10
 
 The first release.
 
@@ -136,5 +149,6 @@ The first release.
 - `Capability` flags and plugin contracts for sources, targets, and embedding providers.
 - `vecshift fingerprint` and `vecshift --version` commands.
 
-[Unreleased]: https://github.com/Osamamu64/vecshift/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Osamamu64/vecshift/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Osamamu64/vecshift/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Osamamu64/vecshift/releases/tag/v0.1.0

{vecshift-0.1.0 → vecshift-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vecshift
-Version: 0.1.0
+Version: 0.2.0
 Summary: Zero-downtime embedding model migrations for pgvector and Supabase: plan, re-embed, evaluate, and cut over safely.
 Project-URL: Homepage, https://github.com/Osamamu64/vecshift
 Project-URL: Repository, https://github.com/Osamamu64/vecshift
@@ -44,6 +44,9 @@ Description-Content-Type: text/markdown
 **Safe, observable embedding migrations for any vector store, with any embedding model.**
 
 [![CI](https://github.com/Osamamu64/vecshift/actions/workflows/ci.yml/badge.svg)](https://github.com/Osamamu64/vecshift/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vecshift)](https://pypi.org/project/vecshift/)
+[![Python](https://img.shields.io/pypi/pyversions/vecshift)](https://pypi.org/project/vecshift/)
+[![Docker image](https://img.shields.io/badge/docker-ghcr.io%2Fosamamu64%2Fvecshift-2496ED?logo=docker&logoColor=white)](https://github.com/Osamamu64/vecshift/pkgs/container/vecshift)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/Osamamu64/vecshift/blob/main/LICENSE)
 ![Status: alpha](https://img.shields.io/badge/status-alpha-orange)
 
@@ -181,14 +184,24 @@ the [benchmarking guide](https://github.com/Osamamu64/vecshift/blob/main/docs/be
 
 ### Plan a migration
 
+```bash
+vecshift init
+```
+
+At a terminal, `init` walks you through it: paste your connection string (hidden as you
+type), pick the vector column and the text it came from, choose the new model, and set a
+spending limit. It writes a commented `vecshift.yaml`, can save the connection string to
+a private `.env` file if you want it to, and shows the plan. For scripts, pass everything
+as flags:
+
 ```bash
 vecshift init --table public.documents --model openai/text-embedding-3-large,dims=1024
 vecshift plan
 ```
 
-`init` writes a commented `vecshift.yaml`. `plan` checks it against the database without
-changing anything: the SQL it would run, rows, tokens, cost, duration, and storage, plus
-anything that would make the migration fail.
+`plan` checks the job against the database without changing anything: the SQL it would
+run, rows, tokens, cost, duration, and storage, plus anything that would make the
+migration fail.
 
 ### Run it
 
@@ -201,6 +214,7 @@ concurrently, while your application keeps reading and writing. It stops cleanly
 Ctrl-C, at your budget, or part way with `--until 50`, and running it again resumes.
 
 ```bash
+vecshift status            # where it stands, and what to run next
 vecshift eval              # better on your data, and how fast? GO / NO-GO
 vecshift cutover --check   # safe to switch?
 vecshift cutover           # searches use the new vectors, under the same column name

{vecshift-0.1.0 → vecshift-0.2.0}/README.md

@@ -8,6 +8,9 @@
 **Safe, observable embedding migrations for any vector store, with any embedding model.**
 
 [![CI](https://github.com/Osamamu64/vecshift/actions/workflows/ci.yml/badge.svg)](https://github.com/Osamamu64/vecshift/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vecshift)](https://pypi.org/project/vecshift/)
+[![Python](https://img.shields.io/pypi/pyversions/vecshift)](https://pypi.org/project/vecshift/)
+[![Docker image](https://img.shields.io/badge/docker-ghcr.io%2Fosamamu64%2Fvecshift-2496ED?logo=docker&logoColor=white)](https://github.com/Osamamu64/vecshift/pkgs/container/vecshift)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 ![Status: alpha](https://img.shields.io/badge/status-alpha-orange)
 
@@ -145,14 +148,24 @@ the [benchmarking guide](docs/bench.md).
 
 ### Plan a migration
 
+```bash
+vecshift init
+```
+
+At a terminal, `init` walks you through it: paste your connection string (hidden as you
+type), pick the vector column and the text it came from, choose the new model, and set a
+spending limit. It writes a commented `vecshift.yaml`, can save the connection string to
+a private `.env` file if you want it to, and shows the plan. For scripts, pass everything
+as flags:
+
 ```bash
 vecshift init --table public.documents --model openai/text-embedding-3-large,dims=1024
 vecshift plan
 ```
 
-`init` writes a commented `vecshift.yaml`. `plan` checks it against the database without
-changing anything: the SQL it would run, rows, tokens, cost, duration, and storage, plus
-anything that would make the migration fail.
+`plan` checks the job against the database without changing anything: the SQL it would
+run, rows, tokens, cost, duration, and storage, plus anything that would make the
+migration fail.
 
 ### Run it
 
@@ -165,6 +178,7 @@ concurrently, while your application keeps reading and writing. It stops cleanly
 Ctrl-C, at your budget, or part way with `--until 50`, and running it again resumes.
 
 ```bash
+vecshift status            # where it stands, and what to run next
 vecshift eval              # better on your data, and how fast? GO / NO-GO
 vecshift cutover --check   # safe to switch?
 vecshift cutover           # searches use the new vectors, under the same column name

{vecshift-0.1.0 → vecshift-0.2.0}/demo/run.sh

@@ -55,6 +55,9 @@ fi
 step "6. Switch searches to the new vectors" "vecshift cutover --yes"
 vecshift cutover --yes
 
+step "7. Check where it stands" "vecshift status"
+vecshift status
+
 printf '\nDone. Searches now use the new vectors, under the same column name.\n'
 printf 'Reports: demo/out/doctor.html and demo/out/eval.html\n'
 printf 'To switch back: docker compose run --rm --entrypoint vecshift vecshift rollback --yes\n'

{vecshift-0.1.0 → vecshift-0.2.0}/docs/demo.md

@@ -30,6 +30,7 @@ in the vecshift container:
    and writes `demo/out/eval.html`. If the verdict isn't GO, the demo stops here.
 7. **`vecshift cutover`** renames the columns in one transaction, so `embedding` now holds
    the new vectors.
+8. **`vecshift status`** confirms the stage and says what to do next.
 
 Afterwards you can switch back, or run any other command, against the same database:
 

{vecshift-0.1.0 → vecshift-0.2.0}/docs/migrations.md

@@ -36,7 +36,21 @@ by one model can't be compared with vectors from another.
 
 ## The job file
 
-`vecshift init` writes a commented `vecshift.yaml`. The full set of settings:
+`vecshift init` writes a commented `vecshift.yaml`. Run it at a terminal without flags and
+it asks for what it needs:
+
+1. The connection string, unless `VECSHIFT_DSN` or `DATABASE_URL` is already set. It's
+   hidden as you type, checked by connecting, and asked again if it doesn't work.
+2. The vector column, from the ones it finds, and the column holding the source text.
+3. The model that made the current vectors (optional, for `eval`), the new model from a
+   short list or any spec, and a spending limit for paid models.
+
+It then offers to save the connection string, and any API key the model needs, to `.env`
+(see below), and to run `plan`. Saving defaults to no: nothing is written to disk unless
+you say yes. With `--table` and `--model`, `init` asks nothing, for scripts; and
+without a terminal it requires them.
+
+The full set of settings:
 
 ```yaml
 version: 1
@@ -68,6 +82,32 @@ The file never contains credentials: the connection string comes from the enviro
 variable that `dsn_env` names. Sections whose settings are all commented out use the
 defaults, and unknown settings are rejected so typos don't go unnoticed.
 
+### Settings in a `.env` file
+
+Every command reads `.env` from the current folder, if there is one, so you don't have to
+export variables in each shell:
+
+```bash
+VECSHIFT_DSN='postgresql://postgres.<ref>:<password>@<region>.pooler.supabase.com:5432/postgres'
+OPENAI_API_KEY='sk-...'
+```
+
+Variables already set in the environment win over the file. Use `--env-file PATH` to read
+another file, or `--no-env-file` to read none. Keep the file private (`chmod 600 .env`;
+vecshift warns if others can read it) and out of version control. When `init` saves to
+it, it creates the file readable by you only, and offers to add it to `.gitignore`.
+
+## Where a migration stands
+
+```bash
+vecshift status            # or --json, for scripts and UIs
+```
+
+`status` is read-only. It shows the stage (not started, filling the new column, ready to
+cut over, cut over, or done), how many rows have a new vector, the index and sync
+trigger, what `apply` has spent, the last cutover or rollback, and the command to run
+next.
+
 ## What `plan` checks
 
 `plan` connects read-only, samples the table, and reports what `apply` would do, what it

{vecshift-0.1.0 → vecshift-0.2.0}/docs/security.md

@@ -40,6 +40,11 @@ and how it protects credentials. To report a vulnerability, see
   - Credentials inside URLs (`https://user:pass@...`) are rejected, and URL query strings
     are hidden wherever a spec is displayed.
 - Error messages from providers are shortened and never include the request's key.
+- **`.env` files** are an optional alternative to exporting variables. They're read from
+  the current folder (or `--env-file`), never override variables already set, and
+  vecshift warns when other users can read one. `vecshift init` types secrets hidden, and
+  saves them to `.env` only when you say yes: the file is created `0600`, and init offers
+  to add it to `.gitignore`. Errors in the file name the line, never its value.
 
 ## The database
 
@@ -79,6 +84,7 @@ and how it protects credentials. To report a vulnerability, see
   token and row counts, and the IDs of rows the provider rejected, with the provider's
   error. Never row text or credentials. The directory is `0700` and the file `0600`, and
   it is replaced atomically so a crash can't leave it half-written.
+- **`.env`**: only when you choose to save to it in `vecshift init`, as above.
 - **Files you ask for**: reports and saved queries are written only where you point them.
   Saved generated queries contain the query text and document IDs.
 
@@ -97,7 +103,9 @@ markup, the browser would refuse to run it or send anything anywhere.
   - `zizmor` for GitHub Actions security
   - Ruff's flake8-bandit rules (`S`) for code patterns
 - GitHub Actions are pinned to full commit SHAs, workflows get read-only tokens, and
-  checkout doesn't persist credentials. Dependabot keeps dependencies and pins up to date.
+  checkout doesn't persist credentials. Dependabot keeps dependencies and pins up to date,
+  one grouped pull request per ecosystem a month, and only proposes releases at least two
+  weeks old (security updates aren't delayed).
 - The Docker image is built from a base image pinned by digest, installs dependencies
   from the lock file with `--require-hashes`, and runs as an unprivileged user. The demo's
   database is reachable only from the demo's own containers.

{vecshift-0.1.0 → vecshift-0.2.0}/src/vecshift/__init__.py

@@ -4,7 +4,7 @@ from vecshift.core.capabilities import Capability
 from vecshift.core.fingerprint import EmbeddingFingerprint
 from vecshift.core.record import Record, SparseVector
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "Capability",

{vecshift-0.1.0 → vecshift-0.2.0}/src/vecshift/cli.py

@@ -11,17 +11,20 @@ import typer
 
 from vecshift import __version__
 from vecshift.cli_style import STYLE as _STYLE
-from vecshift.cli_style import warn_if_password_on_command_line
+from vecshift.cli_style import banner, warn_if_password_on_command_line
 from vecshift.cli_style import wrap as _wrap
 from vecshift.core.fingerprint import EmbeddingFingerprint
 from vecshift.doctor import Report, Severity, run_checks
+from vecshift.envfile import DEFAULT as DEFAULT_ENV_FILE
+
+TAGLINE = "Safe, observable embedding migrations for any vector store."
 
 app = typer.Typer(
     name="vecshift",
     # Tracebacks must never print local variables: they can hold connection strings and keys.
     pretty_exceptions_show_locals=False,
-    help="Safe, observable embedding migrations for any vector store.",
-    no_args_is_help=True,
+    help=TAGLINE,
+    invoke_without_command=True,
     add_completion=False,
 )
 
@@ -32,8 +35,27 @@ def _print_version(value: bool) -> None:
         raise typer.Exit()
 
 
+def _load_env_file(path: Path | None) -> None:
+    from vecshift import envfile
+
+    if path is None:
+        return
+    try:
+        envfile.load(path)
+    except envfile.EnvFileError as exc:
+        typer.secho(f"Couldn't read {path}: {exc}", err=True, fg=typer.colors.RED)
+        raise typer.Exit(2) from exc
+    if envfile.readable_by_others(path):
+        typer.secho(
+            f"Warning: other users of this machine can read {path}. Run: chmod 600 {path}",
+            err=True,
+            fg=typer.colors.YELLOW,
+        )
+
+
 @app.callback()
 def main(
+    ctx: typer.Context,
     version: Annotated[
         bool,
         typer.Option(
@@ -43,8 +65,23 @@ def main(
             help="Show the version and exit.",
         ),
     ] = False,
+    env_file: Annotated[
+        Path,
+        typer.Option(
+            dir_okay=False,
+            help="Read settings such as VECSHIFT_DSN from this file, if it exists. Variables "
+            "already set in the environment take precedence.",
+        ),
+    ] = DEFAULT_ENV_FILE,
+    no_env_file: Annotated[
+        bool, typer.Option("--no-env-file", help="Don't read a .env file.")
+    ] = False,
 ) -> None:
     """Safe, observable embedding migrations for any vector store."""
+    _load_env_file(None if no_env_file else env_file)
+    if ctx.invoked_subcommand is None:
+        banner(__version__, TAGLINE)
+        typer.echo(ctx.get_help())
 
 
 @app.command()
@@ -218,7 +255,8 @@ from vecshift.cli_bench import bench  # noqa: E402
 
 app.command()(bench)
 
-from vecshift.cli_plan import init, plan  # noqa: E402
+from vecshift.cli_init import init  # noqa: E402
+from vecshift.cli_plan import plan  # noqa: E402
 
 app.command()(init)
 app.command()(plan)
@@ -234,3 +272,7 @@ app.command()(cleanup)
 from vecshift.cli_eval import eval_  # noqa: E402
 
 app.command(name="eval")(eval_)
+
+from vecshift.cli_status import status  # noqa: E402
+
+app.command()(status)