@functional-systems/lambdadb-cli 0.1.0-dev.1

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0-dev.1] - 2026-09-18
+
+### Added
+
+- Project-scoped configure, doctor, collection list/describe/create, JSONL import,
+  ID fetch and query commands using LambdaDB TypeScript SDK 0.5.1.
+- Explicit targets, branch/tag/alias read refs, bounded requests, noninteractive
+  operation and versioned JSON output with documented exit codes.
+- Sequential ordinary/bulk imports that distinguish acceptance, rejection,
+  partial completion and unknown outcomes without promising search readiness.
+- Local transport contracts, installed-package contracts, release metadata checks
+  and an opt-in development-project live smoke with temporary collection cleanup.
+- Development/release procedures and a prepared npm OIDC publishing workflow.
+- Opt-in automatic develop publication after Node 22/24 CI, deterministic dev
+  build versions, exact-artifact rerun verification and stale-build guards.
+  Explicit rc/stable releases continue to require reviewed main history.
+- Apache-2.0 license text and package license metadata.
+
+### Fixed
+
+- Live smoke observes committed documents for up to 300 seconds per read stage
+  and reports safe progress diagnostics after a 75-second observation failure.
+  Requests and polling sleeps respect the remaining budget; late results cannot
+  pass. The validation record identifies the designated development target.
+- Colliding redacted document/metadata keys receive unique suffixes instead of
+  silently overwriting values; unchanged field names remain intact.
+- Credential redaction preserves fixed JSON fields, command/status tokens and
+  error categories when a credential is short or matches a protocol token.
+- JSONL preflight caps imports at 100,000 documents and scans physical lines
+  without a split array, rejecting excess small documents before any API call.
+- Command deadlines are bound at SDK fetch dispatch to avoid a reproduced stalled
+  second write; signal cancellation preserves acknowledged and unknown outcomes.
+
+### Release status
+
+Prepared for the first public development release on npm's `dev` channel. This
+entry records the candidate contents and preparation date, not a publication.
+The development-project smoke is recorded in VALIDATION.md. npm organization
+permission verification, authorized bootstrap publication and Trusted Publishing
+setup remain pending. Automatic dev publication is disabled until maintainers
+enable `NPM_DEV_PUBLISH_ENABLED`; main promotion is required only for rc/stable.

package/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing
+
+## Branches and pull requests
+
+`main` is the default branch and the reviewed rc/stable release baseline.
+`develop` integrates changes and supplies automatic npm development builds.
+Branch names here refer to Git branches,
+not LambdaDB collection branches or refs.
+
+1. Create a short-lived `feat/*` or `fix/*` branch from current `develop`.
+2. Implement and validate one coherent change.
+3. Open a pull request targeting `develop`. GitHub defaults new pull requests to
+   `main`, so select the base explicitly.
+4. Address review feedback and pass both required CI checks before merging.
+5. Delete the short-lived branch after verifying the merge.
+
+For the initial MVP, `feat/cli-mvp` targets the initial `develop` commit. The
+review includes the CLI implementation, tests, documentation and CI setup.
+
+## Local and CI validation
+
+```sh
+npm ci
+npm run lint
+npm run check:version
+npm run typecheck
+npm test
+npm run test:package
+```
+
+The `CI` workflow in `.github/workflows/publish.yaml` runs on pull requests
+targeting `develop` or `main` and on
+pushes to those branches. Its required check names are `Node.js 22` and
+`Node.js 24`. Both install the lockfile, lint, validate version metadata, check
+types, build, run the mock/local contract suite, and repeat the CLI contract
+tests against a separately installed tarball. Use Node.js 22.14 or newer locally.
+Validation jobs use a read-only GitHub token and no LambdaDB credentials. They
+do not publish packages or contact a LambdaDB service. After both jobs succeed,
+an eligible develop push can publish a dev package using a separate OIDC-enabled
+job. PRs, main pushes and manual CI runs cannot publish development packages.
+Automatic publication requires `NPM_DEV_PUBLISH_ENABLED=true`; enabling it after
+npm bootstrap and trust setup authorizes this ongoing behavior.
+
+Both long-lived branches require pull requests, one approving review, resolved
+review conversations, and both CI checks against an up-to-date base. New commits
+dismiss prior approvals. Force pushes and branch deletion are disabled. Repository
+administrators are also subject to the repository's branch protection.
+
+The organization additionally applies its `protect-main` ruleset to the default
+branch. Its update restriction allows designated team members to merge through
+the organization's PR-only bypass; passing repository CI alone does not grant
+permission to update `main`. Repository rules do not weaken organization rules.
+
+## Promoting a release
+
+Development builds do not require main promotion or manual version increments.
+CI derives a unique version from the reviewed development base and first-parent
+commit count. Keep the base in `X.Y.Z-dev.N` form; when moving to the next release
+line, update it and the lockfile through a PR. Generated build versions are not
+committed back. Stale queued builds can be skipped as newer work arrives.
+
+For an rc/stable release, once changes and validation are complete on `develop`, open a
+`develop` → `main` pull request. Record the version, changes, local/CI evidence,
+and whether live verification was performed. Merge this promotion using a merge
+commit so the shared branch ancestry is preserved. After promotion, synchronize
+`main` back into `develop` through a PR when it contains commits absent from
+`develop`, especially release-only changes or hotfixes. Include the next intended
+development base in that synchronization PR so develop retains a dev version.
+
+A separate `release/*` branch is optional when stabilization must proceed while
+new work continues on `develop`. It is not required for the initial release.
+
+The first npm bootstrap, rc/stable tags and GitHub Releases remain explicit
+release actions. Subsequent dev publication is automatic once enabled.
+The `0.1.0-dev.1` candidate sets `private: false` and prepares metadata
+for the `dev` channel; the development-project smoke is recorded in
+[VALIDATION.md](VALIDATION.md), and publication remains pending. Follow
+[RELEASING.md](RELEASING.md) for package preparation, version/channel rules,
+credentialed live evidence, initial npm bootstrap and Trusted Publishing.
+Local tests and PR validation alone never trigger publication.
+
+For an urgent released-version fix, branch from `main`, review a PR back to
+`main`, then synchronize the fix into `develop`. Preserve the same checks and
+review requirements.
+
+## Credentials and scope
+
+Never commit project keys, `.env` files or signed URLs. Runtime tests use loopback
+servers with synthetic credentials. Live tests require an explicitly designated
+development project and credential set; local or CI success is not proof of
+live-service readiness. See [README.md](README.md) and
+[VALIDATION.md](VALIDATION.md) for the current contract and evidence boundaries.
+
+## Compatibility and maintenance
+
+Treat documented flags, JSON schema, exit codes, explicit target selection and
+failure semantics as public contracts. Add regression coverage for changes to
+these behaviors; do not script against human summaries. Update the changelog
+and document a migration when changing a contract. Preserve `--help` and
+noninteractive operation in the installed artifact, not only the source tree.
+
+Review dependency updates through the same PR checks, including the actual SDK
+contract and installed-package tests. Keep workflow actions pinned to commit
+SHAs and document version updates in their comments. Do not copy another
+repository's runtime matrix or release tooling without checking this CLI's needs.

package/DESIGN.md

@@ -0,0 +1,112 @@
+# LambdaDB CLI MVP design
+
+## Evidence baseline
+
+Inspected on 2026-09-18. Source/API verification is not live-service validation.
+
+| Evidence | Observed contract |
+| --- | --- |
+| [TypeScript SDK source](https://github.com/lambdadb/lambdadb-typescript-client/tree/856abf48a014185de54ccc541c2f6ee3871133ee) | Local reference checkout was clean at this commit, version 0.5.1. |
+| npm `@functional-systems/lambdadb` registry | `latest=0.5.1`; installed published package exactly at 0.5.1, not a local file dependency. |
+| [Public OpenAPI](https://github.com/lambdadb/docs/blob/9a4eaf1e71b7809708a77101751ce2a5c4815fcb/reference/api/openapi.json) | API version 1.1.1; collection create 201, ordinary/bulk write acceptance 202, ref-aware query/fetch, no generic mutation-readiness receipt. |
+| [Public quickstart](https://docs.lambdadb.ai/guides/get-started/quickstart) | Existing Console project/key setup, collection creation, writes, reads and eventual visibility. |
+
+Fetched OpenAPI SHA-256:
+`ad930a79ab27115a326bde6dff69c472670f8ba0eda65dde1c5f01ff76678563`.
+Published SDK integrity:
+`sha512-AvchiWlbV9r7ihizmBG+oacwzXAvq9WKHoEmXYCkkHbWVBBvunwlxyzKQBd+0V2q2XjIkNKhHBZ3ytAhj1pArg==`.
+Installed `client.ts` and query request schema matched the inspected local source.
+The lockfile pins the dependency graph.
+
+Read-only design inputs:
+
+- `/Users/steven/orca/projects/sbrain/AGENTS.md`
+- `/Users/steven/orca/projects/sbrain/projects/lambdadb-code-search-demo.md`
+- `/Users/steven/orca/projects/sbrain/knowledge/product/lambdadb-mcp-server-design.md`
+- `/Users/steven/orca/projects/sbrain/knowledge/product/lambdadb-mcp-implementation-plan.md`
+- `/Users/steven/Dev/lambdadb-typescript-client`
+
+The code-search document describes an application proposal, not delivered generic
+CLI behavior. The MCP design's hosted authentication, readiness workflows and
+workflow SDK additions are proposals. Its September 14 registry baseline
+(`latest=0.4.3`, versioning RC) is superseded by the verified 0.5.1 publication.
+This CLI reuses currently available SDK capabilities; it does not assume proposed
+`ingestDocuments`, `waitForDocuments` or mutation receipts exist.
+
+## Architecture
+
+```text
+CLI arguments/configuration → input validation → SDK facade → LambdaDB APIs
+                                      ↓              ↓
+                              import workflow   signed transfers
+                                      ↓
+                         structured result / terminal output
+```
+
+- `cli.ts`: command tree, target selection, SDK calls and process exit codes.
+- `config.ts`: deterministic user-local configuration, environment auth and
+  atomic non-secret settings writes.
+- `input.ts`: bounded file snapshots, strict request preflight, SDK serializer
+  reuse and the small null-size compatibility adjustment.
+- `import-workflow.ts`: byte/count batching, sequential submission, honest
+  outcome accounting and progress callbacks, independent of terminal I/O.
+- `runtime.ts`: SDK construction, shared abort deadline and bounded read retries.
+- `errors.ts` and `output.ts`: safe error classification, versioned output and
+  credential redaction.
+
+There is no second HTTP implementation, separate workflow package, plugin system
+or SDK fork. `listCollectionsPages` owns pagination. `bulkUpsertDocs` owns upload
+metadata, signed PUT, server-provided byte limit and finalization. Query/fetch
+helpers own presigned response downloads and authentication isolation.
+
+## Contract decisions
+
+| Decision | Reason |
+| --- | --- |
+| Mandatory endpoint/project resolution, explicit collection, read ref and write branch | Avoid SDK playground/main fallbacks silently choosing a target. |
+| Environment-held keys only | Keeps secrets out of argv and repository/user configuration files. |
+| Read retry policy bounded through SDK, no mutation retries | No public exactly-once or mutation receipt contract; a missing reply cannot prove rejection. |
+| Entire JSONL preflight before writes | A malformed later line must not unexpectedly leave accepted earlier batches. |
+| 64 MiB / 100,000-document input caps, 4 MB ordinary batches, configurable bulk batches | Bound file size and retained row overhead without building streaming/checkpoint infrastructure; scan lines without a full split array. |
+| SDK request serializers for validation | Keep create/query shapes aligned; query DSL semantics remain server-owned. |
+| Versioned JSON envelope and documented exits | Stable automation contract with explicit target and partial progress. |
+| Preserve fixed output keys/tokens during redaction | Short credentials must not corrupt the CLI protocol; redact variable values and arbitrary document/index/tag map keys. |
+| Conservative unknown state for untyped bulk helper failures | Error strings are not a reliable upload/finalization stage contract. |
+| No readiness wait or version-management commands | First use works through main; reads can target existing refs, without assuming lifecycle or indexing guarantees. |
+
+The public API documents ordinary upsert at 6 MB and bulk at 200 MB; CLI limits
+are deliberately smaller. Bulk is unsupported for managed embedding vector
+fields. `consistentRead` only supports direct branches and excludes pending bulk
+imports. Collection statistics describe committed main, not selected ref readiness.
+
+## SDK compatibility findings
+
+No upstream edit was required. Local regressions cover these adaptation points:
+
+1. Public query `size: null` means default size, but SDK 0.5.1's serializer accepts
+   only number/undefined. Normalize null to omission and enforce public 1–100 bounds.
+   An upstream schema-alignment change would remove this adapter.
+2. `SDKValidationError[Symbol.hasInstance]` intentionally also matches
+   `ResponseValidationError`. Check response validation first and exclude it from
+   local input errors; otherwise a malformed 202 response is misclassified as a
+   definite local failure rather than an unknown write outcome.
+3. SDK debug logging is environment-controlled. Supplying a no-op logger still
+   clones/drains HTTP bodies. An initial loopback timeout regression left the
+   process alive with that logger. The CLI instead removes `LAMBDADB_DEBUG` from
+   its own process before SDK construction and supplies no logger. The same
+   timeout case now completes and preserves the unknown outcome.
+4. The bulk helper throws ordinary unstructured errors for upload and size
+   failures. A future typed stage/error contract would enable more precise
+   failed-versus-unknown reporting. The current CLI never parses error messages
+   or claims a finalize receipt.
+5. Expanded installed-package tests reproduced a stalled second upsert despite a
+   600 ms command timeout on Node 24.15.0. Retaining an explicit timer alone did
+   not eliminate it. The CLI now binds its command signal directly at fetch
+   dispatch through the SDK's supported HTTPClient hook, for separate API and
+   transfer clients. SDK authentication, request construction, retry and transfer
+   logic remain in use. Local source and installed-package regressions verify
+   timeout and SIGINT/SIGTERM accounting. The precise upstream/runtime root cause
+   has not been established; no reference SDK source was changed.
+
+These findings do not require a new SDK release to use the CLI. SDK updates should
+retain contract tests before changing the pinned version.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.