harvask-cli 0.3.1 → 0.6.0

package/skills/harvask/SKILL.md

@@ -43,6 +43,12 @@ If a command fails with an auth error (exit code 3), run `harvask login` again.
    harvask issue assign -p PRJ 1234 --assignee-id 42
    ```
 
+## Migrating an existing project
+
+Bringing a local directory (or another tool's export) into a harvask project has its own
+rules — where files should go, what must never be uploaded, and why a live session blocks
+writes. Read `migration.md` in this skill directory before pushing anything.
+
 ## project key vs id
 
 - Humans know the **key** (e.g. `PRJ`); the API uses a numeric **id**.
@@ -71,6 +77,25 @@ If a command fails with an auth error (exit code 3), run `harvask login` again.
   ```
 - The `api` escape hatch accepts a JSON body the same way (`@body.json`, `-`).
 
+## Deliverable declarations
+
+- `issue create/update --deliverable <json>` attaches the deliverable the work
+  must produce (inline JSON, `@decl.json`, or `-`). Only `type`
+  (`text|file|none`) is required. Optional fields are `label`, `note`,
+  `required`, `rules` (`min_chars`, `max_chars`, `required_keywords`,
+  `required_headings`, `format`, `extensions`, `max_rework`), `judge`
+  (`enabled`, `criteria`), and `builder` (`enabled`, `instructions`).
+  ```
+  harvask issue create -p PRJ --title "Notice" --deliverable '{"type":"text","rules":{"min_chars":60}}'
+  harvask issue update -p PRJ PRJ-1 --deliverable null   # remove the declaration
+  ```
+- Omitting `--deliverable` on `update` leaves the declaration untouched.
+- `issue show` returns `issue.deliverable` with three parts:
+  - `config`: the declaration
+  - `final`: the accepted deliverable (`content` or `attachment.download_url`)
+  - `history`: newest first, with `status`, `content_length`, and failed
+    `validation.checks[]`
+
 ## Common errors and what to do
 
 - **exit 3 / 401** — token invalid or expired → `harvask login --tenant <domain>`.
@@ -102,7 +127,7 @@ harvask login | logout | whoami
 
 # project-scoped (pass -p <key|id>)
 harvask project        list | show <key|id> | create | members list|add|remove <key|id>
-harvask issue          list | show | create | update | search | status | assign
+harvask issue          list | show | create | update (--deliverable <json|null>) | search | status | assign
 harvask issue comment      list | create
 harvask issue todo         list | show | create | update | delete
 harvask issue memory       list | show | create | update | delete
@@ -111,9 +136,10 @@ harvask issue bulk-create | bulk-update      (--items @file.json [--atomic])
 harvask wiki           list | show | create | update (--base-version required) | search | set-home | history | delete | bulk-create | bulk-update
 harvask milestone      list | create | update
 harvask workflow       list | show | create | update | execute (non-idempotent, --yes required non-interactively)
-harvask scheduled-task list | show | create | update | delete
+harvask scheduled-task list | show | create | update | execute (non-idempotent, --yes required non-interactively) | delete
 harvask file           search | stats
-harvask storage        list | search | stats | upload | folder | move | rename | delete | download | content
+harvask storage        list | search | stats | upload (--on-conflict rename|overwrite|error) | folder | move | rename | delete | download | content
+harvask workspace      push <dir> (--dest, --dry-run, --exclude)   # local tree -> AI workspace
 harvask preview-config show | update
 harvask site-credential                       # list browser credentials
 
@@ -132,5 +158,14 @@ Notes:
 - `personal-wiki` is intentionally not available via the CLI.
 - File/binary: `storage upload` / `attachment upload` take `--file <path>`;
   `storage download` / `attachment download` save with `--out <path>`.
+  `attachment upload --type chat_message` also needs `--chat-id <id>`.
+- `project create --key` is optional; without it the server derives a unique key
+  from `--name`.
+- `scheduled-task` has three execution types: `issue`, `workflow` and `chat`
+  (`--chat-message` is the body, required for chat). `update` changes only the
+  fields you pass, including the schedule (`--frequency` / `--time` /
+  `--day-of-week` / `--day-of-month` / `--cron`). Fields that do not belong to
+  the resulting execution type are rejected by the CLI, because the server
+  silently drops them.
 
 Use `harvask <command> --help` for options, examples, and prerequisites.

package/skills/harvask/migration.md

@@ -0,0 +1,72 @@
+# Migrating an existing local project into harvask
+
+Use this when someone wants to bring a project that lives on their machine (or in another
+tool) into a harvask project: source trees, design docs, spreadsheets, legacy assets.
+
+## First: pick the destination. They are not interchangeable.
+
+| What you have | Where it goes | How |
+|---|---|---|
+| Code in a git repository | **Keep it in git.** Link the repo in the project settings (Web UI: Settings > Repository) | No migration needed — AI sessions clone it |
+| Files the AI should work on directly: docs, data, assets, legacy scripts, a non-git tree | **AI workspace** (Files tab = `~/work` in AI sessions) | `harvask workspace push` |
+| Reference documents people will search and share | **Storage** | `harvask storage upload` |
+| Knowledge that should be read, edited and versioned as text | **Wiki** | `harvask wiki create` / `global-wiki` |
+
+If the answer is "code that is already in git", say so and stop — pushing a clone into the
+workspace duplicates it and the copies drift apart.
+
+## Workspace push
+
+```bash
+harvask workspace push ./legacy-app -p PRJ --dest legacy --dry-run   # plan only, sends nothing
+harvask workspace push ./legacy-app -p PRJ --dest legacy --yes       # do it
+```
+
+Always run `--dry-run` first and show the plan (`would_create` / `would_overwrite` /
+`skipped` / `excluded`) before sending anything. Overwrites are silent and there is no
+version history, so `--yes` is required to overwrite in a non-interactive shell.
+
+### Rules that bite
+
+- **Never push `.env` or credentials.** The CLI excludes `.env*` and cannot be told
+  otherwise, because the workspace is visible to every project member. If secrets are
+  needed by the AI, use project secrets (Web UI), not files.
+- `.gitignore` is respected when the directory is a git repo (the CLI lets `git ls-files`
+  enumerate, so `.git/info/exclude` and your global gitignore count too). `node_modules/`,
+  `vendor/`, `dist/`, `build/`, `__pycache__/`, `.venv/`, `.DS_Store` are excluded by
+  default; `--include-ignored` (everything) or `--include <glob>` (one path) brings them
+  back. `--exclude <glob>` wins over `--include`.
+- Windows binaries and scripts (`.exe .bat .cmd .ps1 .vbs .com .msi .dll`) cannot be
+  stored. They are reported as `skipped`, not treated as an error. `.sh` is allowed, but
+  the workspace has no execute bit — run it as `sh script.sh`.
+- Do not push into `apps/` or `canvas/`. Mini-app sources plus their SQLite data and
+  Canvas documents live there; overwriting them breaks the running app. The CLI refuses
+  unless `--force`, and you should ask the user before reaching for it.
+- Symlinks are not followed (reported as `excluded`), and empty directories are not
+  reproduced (object storage has no directories).
+
+### When it stops
+
+- **409 `workspace_session_active`** — a mini-app or browser-agent session is live for
+  that project. Do **not** retry: while a session runs, the workspace is synced from the
+  session and anything you upload is silently rolled back. End the session, then push.
+- **Invalid paths** — the dry run reports them and the CLI refuses to send. Those paths
+  can never be stored (`..`, empty segments, deeper than 20 levels); one bad path fails a
+  whole request, so fix or drop them.
+- **Partial failure** — batches are not atomic. The result JSON lists `remaining`; re-run
+  the same command to continue. Re-uploading is safe: same path = overwrite.
+- **413 / timeouts** on a slow link — send less per request with
+  `--max-batch-bytes 52428800` and re-run; what already landed is not sent again.
+
+## After the files land
+
+Migration is not finished when the bytes arrive. Leave the AI something to work from:
+
+1. Tell the user what landed and where (`--dest` path), and what was skipped or excluded.
+2. Write down what the project is, how it runs, and what is missing — a project Wiki page
+   (`harvask wiki create -p PRJ`) is the right home; the AI reads it before working.
+3. If the migration exists to get work done, file the first issue
+   (`harvask issue create -p PRJ`) describing that work.
+
+Check the result in the Files tab (`/projects/{id}/files`) or with a fresh `--dry-run`:
+everything should now report as `would_overwrite`, nothing as `would_create`.