agentic-drive 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# agentic-drive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/agentic-drive)](https://www.npmjs.com/package/agentic-drive)
+[![MIT license](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/license/mit)
+
+[Package](https://www.npmjs.com/package/agentic-drive) · [Source](https://github.com/pooriaarab/agentic-drive) · [Support](https://github.com/pooriaarab/agentic-drive/issues)
+
+Store, sort, and share files and folders.
+
+> Status: early (0.1.0). The library, CLI, MCP server, and HTTP API work.
+> Sharing and the web UI are not built yet.
+
+## Install
+
+```sh
+npm install agentic-drive
+```
+
+## Quick start
+
+```ts
+import { createDrive, createFileStore, createFileBlobs } from "agentic-drive";
+
+const drive = createDrive({ store: createFileStore("./data/db"), blobs: createFileBlobs("./data/blobs") });
+const me = { owner: "u1", actor: { id: "u1", kind: "human" as const } };
+
+await drive.mkdir(me, "/reports/2026", { parents: true });
+await drive.putFile(me, "/reports/2026/q1.txt", new TextEncoder().encode("hello"), { mime: "text/plain" });
+await drive.putRef(me, "/reports/plan", "docs:abc123");
+await drive.move(me, "/reports/plan", "/reports/2026");
+await drive.trash(me, "/reports/2026");
+```
+
+## CLI and MCP
+
+```sh
+npx agentic-drive mkdir -p /reports
+npx agentic-drive upload ./q1.pdf /reports/
+npx agentic-drive search --name q1
+npx agentic-drive export ./everything.zip
+npx agentic-drive mcp
+```
+
+Every command prints JSON. A failure prints `{"error":{"code","message"}}` on stderr and exits 1.
+Set `--dir`, `--owner`, `--actor`, and `--actor-kind` (or the `AGENTIC_DRIVE_*` variables).
+An agent sets `--actor-kind agent_of_human`. Each item then records that a machine made it.
+
+## HTTP API
+
+A Cloudflare Worker (Hono) serves `/api/v1/drive` and mirrors the CLI. It uses D1 and R2
+through the shared adapters of `agentic-identity`.
+
+```sh
+npx wrangler secret put DRIVE_API_TOKENS   # {"<token of 32+ characters>":{"owner":"u1","actor":"u1","kind":"human"}}
+npx wrangler secret put DRIVE_URL_SECRET   # 32 bytes or more. It signs download URLs.
+npx wrangler secret put DRIVE_PUBLIC_URL   # The origin of the Worker, such as https://drive.example.com
+npx wrangler deploy
+curl -H "authorization: Bearer <token>" "$URL/api/v1/drive/items?path=/"
+```
+
+Routes: `GET /items`, `GET /stat`, `POST /folders`, `PUT /files`, `GET /files`, `GET /url`,
+`POST /move`, `POST /trash`, `GET /trash`, `POST /restore`, `POST /purge`, `GET /search`,
+`GET /export`, `DELETE /account?confirm=yes`. Without `DRIVE_API_TOKENS`, every request gets 401.
+Without `DRIVE_URL_SECRET` or `DRIVE_PUBLIC_URL`, every request gets 503.
+Create the R2 bucket with `--jurisdiction eu` and the D1 database with `--location weur`.
+The Worker declares region `eu` and refuses a D1 query that a non-EU region served. `DRIVE_REGION=unknown` turns this off for local runs.
+
+## Features
+
+- Folders, files, and typed references to documents in other apps (`docs:<id>`).
+- Paths that start with `/`. Anything else is an item id.
+- Move, rename, trash, restore, and purge. Trashing a folder hides its whole tree.
+- Names compare without regard to case or Unicode form. A clash fails, or renames, or replaces.
+- Each item records its size, type, owner, and who made and last changed it, with the actor kind.
+- Storage sits behind the `Store` and `Blobs` ports of `agentic-identity`. Tests use its memory adapters. The CLI uses a local file adapter that passes the same contract suites. The Worker uses its D1 and R2 adapters.
+- Two live items never share a name in one folder. A claim document holds each name. It is written in the same transaction as the item, and it is deleted when the item goes to the trash.
+- `upload()` reads a stream with a size cap, finds the type from the first bytes, and stores a SHA-256 hash.
+- `downloadUrl()` returns a signed URL. The URL signs an attachment header with the file name and the stored type. The Worker verifies it and serves the bytes with those headers, so the link holder cannot change how the bytes are served. A link lasts 15 minutes by default and 1 hour at most. Trashing a file does not revoke a link already issued.
+- `search()` finds live items by name, type, kind, size, and who made them.
+- `buildExport()` writes everything one owner has to a zip with a `manifest.json`. Trashed items are flagged. Entries are named by item id. A file whose bytes are gone is marked `missing`.
+- `deleteAll()` deletes all items and bytes of one owner for good. Only the owner can call it.
+- A `can()` hook decides who may read, write, or delete. The default allows the owner only.
+
+## Limits
+
+- Drive reads the `store_docs` table in D1 and `store.jsonl` in the CLI folder. It does not read older layouts. There is no import and no claim backfill.
+- Uploads buffer the stream in memory up to the cap. The default cap is 25 MiB.
+- Local file blobs return a `file:` URL that nothing serves or checks.
+- Drive writes each new blob only when its key is free (`ifNoneMatch`). A write that finds the key taken fails with `BLOB_EXISTS`.
+- Only `upload()` enforces the size cap. A caller of `putFile()` must check size first.
+- A claimed type that a browser would run (HTML, SVG, scripts) is stored as `application/octet-stream`.
+- The file adapters allow one process at a time.
+- The MCP `drive_export` tool writes a new `.zip` into `<dir>/exports` and never overwrites a file. It takes a plain file name, not a path.
+- A purge or an erase works in chunks of 25 items, and each chunk commits. A Worker call has a cap on database queries, so a very large tree can need several calls. A failed or cut-off call leaves marked items hidden, and the same call finishes the job.
+- Hard delete removes blobs first and then rows. If a blob delete fails, the call throws and the same call can run again.
+- The export holds every file in memory. A very large drive needs a streaming export, which is not built yet.
+- The zip export stores entries without compression and has no Zip64 support.
+- No access log for personal data yet. That comes with agentic-identity.
+- The D1 store checks every document a transaction read. If another Worker changed one, the transaction runs again, and after 50 tries it fails with a `BUSY` error.
+- The D1 store keeps one generic table. A busy deployment needs an expression index on `owner` and `parentId`.
+- `region: "eu"` on the D1 and R2 adapters is a promise made at deploy time. The D1 adapter refuses a query that a non-EU region served. The code cannot check where the bucket lives.
+- Every API token is at least 32 characters. Its grant names an owner, an actor id, and an actor kind. A grant with a missing part gets 401.
+- Tokens in `DRIVE_API_TOKENS` are a stopgap for sign-in. OIDC comes with agentic-identity.
+- No sharing or roles yet. Roles come from agentic-identity.
+
+## Develop
+
+```sh
+npm ci
+npm run ci:local
+```
+
+## License
+
+MIT.

package/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: agentic-drive
+description: Store, sort, and share files and folders. Keywords: drive,files,folders,storage,upload,sharing,agents,mcp,cli,r2.
+---
+
+# agentic-drive
+
+Store, sort, and share files and folders.
+
+## Use the SDK
+
+```js
+import { createDrive } from "agentic-drive";
+import { createMemoryStore, createMemoryBlobs } from "agentic-identity";
+
+const drive = createDrive({ store: createMemoryStore(), blobs: createMemoryBlobs() });
+const me = { owner: "u1", actor: { id: "u1", kind: "human" } };
+await drive.mkdir(me, "/notes");
+```
+
+## Rules
+
+- A path starts with `/`. Any other locator is an id.
+- Trash before purge.
+- Report a `DriveError` as a failure.

package/dist/chunk-4QE7E5UQ.js

@@ -0,0 +1,7 @@
+// src/version.ts
+import { createRequire } from "module";
+var VERSION = true ? "0.1.0" : readPackageVersion();
+
+export {
+  VERSION
+};