callables 0.1.0__tar.gz

callables-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: callables
+Version: 0.1.0
+Summary: Decorate Python functions and push them to Callables: forms, schedules and run history for your team.
+Project-URL: Homepage, https://callables.app
+Project-URL: Source, https://github.com/callables-app/callables-python
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# Callables Python SDK
+
+Turn Python functions into forms, schedules and run history your whole team can use. Decorate a function with `@deploy`, push the repo, and people run it from the Callables web app — no Python needed on their end.
+
+```bash
+pip install callables
+```
+
+This installs the `call` command. Code written for the SDK's old name, `shipfn`, keeps working: `from shipfn import deploy` and the `shipfn` command are aliases for this package.
+
+```python
+from typing import Literal
+from callables import deploy
+
+@deploy(title="Weekly report", secrets=["SALES_API_TOKEN"], schedule="0 9 * * MON")
+def weekly_report(region: Literal["NA", "EMEA", "APAC"] = "NA", days: int = 7) -> list[dict]:
+    """Deals closed in the last N days."""
+    ...
+```
+
+- **Inputs** come from the type hints: `str`, `int`, `float`, `bool`, `date`, `Literal[...]`/`Enum` (dropdowns), `list[...]`, optional (`X | None`) and Pydantic models. Defaults become prefilled values.
+- **Results** are shown by return type: `str` as Markdown, `list[dict]` (or a DataFrame) as a table with CSV download, `dict`/Pydantic model as a key-value list, `None` as "done".
+- **Files in**: a `File` parameter becomes an upload field. Your function gets a `File` with `.path`, `.name`, `.read_text()`, `.read_bytes()` and `.open()`. Limit the picker with `Annotated[File, accept(".csv", ".xlsx")]`.
+- **Files out**: return a `File` (or a `list[File]`) and people get download buttons. To hand back files alongside another result, call `save_file(path_or_bytes, name=...)`. Files are kept for 24 hours by default.
+- **Secrets** you list are injected as environment variables at run time (`os.environ["SALES_API_TOKEN"]`); set their values in the Callables console.
+- **Schedules** are cron expressions, in UTC.
+
+```python
+from typing import Annotated
+from callables import deploy, File, accept, save_file
+
+@deploy(title="Clean up a sales sheet")
+def clean(sheet: Annotated[File, accept(".csv")]) -> File:
+    rows = sheet.read_text().splitlines()
+    save_file(f"{len(rows)} rows".encode(), name="summary.txt")   # an extra download
+    out = "/tmp/clean.csv"
+    ...
+    return File(out, name=f"clean-{sheet.name}")
+```
+
+Try a function on your machine before pushing:
+
+```bash
+call check                                   # problems a deploy would hit, with fixes (exit 1 on errors)
+call weekly_report --region EMEA --days 30   # every function is also a CLI command
+call local weekly_report -i region=EMEA -i days=30
+call local clean -i sheet=@sales.csv         # @path passes a file; outputs land in ./callables-output/
+call manifest                                # what the platform will see
+```
+
+## Coding agents
+
+The SDK carries its own guide for Claude Code, Cursor, Codex and other agents:
+
+```bash
+call init   # an example automation, .claude/skills/callables/SKILL.md and an AGENTS.md section
+call docs   # print the full guide
+```
+
+`call check --json` and `call local ... --json` print one JSON object on stdout, so an agent can check and run functions and read the result. Re-run `call init` after upgrading the SDK to refresh the instructions. Your own files and the rest of AGENTS.md are left alone.
+
+On the platform, builds use the server's own copy of this package, so you don't need to add `callables` to your `requirements.txt` (it's fine if you do).
+
+## Developing the SDK
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+The platform (shipfn-api) depends on this package and copies the installed version into every build, so a release only reaches deployed functions once the API is updated to it. See [RELEASING.md](RELEASING.md).

callables-0.1.0/README.md

@@ -0,0 +1,71 @@
+# Callables Python SDK
+
+Turn Python functions into forms, schedules and run history your whole team can use. Decorate a function with `@deploy`, push the repo, and people run it from the Callables web app — no Python needed on their end.
+
+```bash
+pip install callables
+```
+
+This installs the `call` command. Code written for the SDK's old name, `shipfn`, keeps working: `from shipfn import deploy` and the `shipfn` command are aliases for this package.
+
+```python
+from typing import Literal
+from callables import deploy
+
+@deploy(title="Weekly report", secrets=["SALES_API_TOKEN"], schedule="0 9 * * MON")
+def weekly_report(region: Literal["NA", "EMEA", "APAC"] = "NA", days: int = 7) -> list[dict]:
+    """Deals closed in the last N days."""
+    ...
+```
+
+- **Inputs** come from the type hints: `str`, `int`, `float`, `bool`, `date`, `Literal[...]`/`Enum` (dropdowns), `list[...]`, optional (`X | None`) and Pydantic models. Defaults become prefilled values.
+- **Results** are shown by return type: `str` as Markdown, `list[dict]` (or a DataFrame) as a table with CSV download, `dict`/Pydantic model as a key-value list, `None` as "done".
+- **Files in**: a `File` parameter becomes an upload field. Your function gets a `File` with `.path`, `.name`, `.read_text()`, `.read_bytes()` and `.open()`. Limit the picker with `Annotated[File, accept(".csv", ".xlsx")]`.
+- **Files out**: return a `File` (or a `list[File]`) and people get download buttons. To hand back files alongside another result, call `save_file(path_or_bytes, name=...)`. Files are kept for 24 hours by default.
+- **Secrets** you list are injected as environment variables at run time (`os.environ["SALES_API_TOKEN"]`); set their values in the Callables console.
+- **Schedules** are cron expressions, in UTC.
+
+```python
+from typing import Annotated
+from callables import deploy, File, accept, save_file
+
+@deploy(title="Clean up a sales sheet")
+def clean(sheet: Annotated[File, accept(".csv")]) -> File:
+    rows = sheet.read_text().splitlines()
+    save_file(f"{len(rows)} rows".encode(), name="summary.txt")   # an extra download
+    out = "/tmp/clean.csv"
+    ...
+    return File(out, name=f"clean-{sheet.name}")
+```
+
+Try a function on your machine before pushing:
+
+```bash
+call check                                   # problems a deploy would hit, with fixes (exit 1 on errors)
+call weekly_report --region EMEA --days 30   # every function is also a CLI command
+call local weekly_report -i region=EMEA -i days=30
+call local clean -i sheet=@sales.csv         # @path passes a file; outputs land in ./callables-output/
+call manifest                                # what the platform will see
+```
+
+## Coding agents
+
+The SDK carries its own guide for Claude Code, Cursor, Codex and other agents:
+
+```bash
+call init   # an example automation, .claude/skills/callables/SKILL.md and an AGENTS.md section
+call docs   # print the full guide
+```
+
+`call check --json` and `call local ... --json` print one JSON object on stdout, so an agent can check and run functions and read the result. Re-run `call init` after upgrading the SDK to refresh the instructions. Your own files and the rest of AGENTS.md are left alone.
+
+On the platform, builds use the server's own copy of this package, so you don't need to add `callables` to your `requirements.txt` (it's fine if you do).
+
+## Developing the SDK
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+The platform (shipfn-api) depends on this package and copies the installed version into every build, so a release only reaches deployed functions once the API is updated to it. See [RELEASING.md](RELEASING.md).

callables-0.1.0/callables/GUIDE.md

@@ -0,0 +1,236 @@
+# Writing Callables automations
+
+Callables turns Python functions into web forms that non-technical teammates run. A developer decorates a function with `@deploy` and pushes the repo. The platform builds it and shows each function as a form, generated from the type hints, with run history. People can also schedule runs from the web app.
+
+The person running an automation can't see the code, a traceback or a terminal. Everything they see comes from the decorator, the docstring, the parameter names and types, and the return value. Write for them.
+
+## The loop
+
+1. Write or change a function decorated with `@deploy`.
+2. `call check` (or `call check --json`) lists every problem a deploy would hit, with a fix for each. Exit code 1 means the deploy would fail.
+3. `call local <name> -i key=value --json` runs the function on this machine, with the same input validation as the platform.
+4. Push. The platform builds and deploys on push.
+
+Run `call check` before every push. If any module fails to import, nothing is published.
+
+### First-time setup
+
+1. Install the CLI into the project's virtualenv: `pip install callables`. Keep it out of `requirements.txt`, because the platform adds its own copy.
+2. The project must be a GitHub repo. Callables deploys a repo and branch, not a local folder. Commit and push it first, with `.env`, key files and data kept out by `.gitignore`.
+3. In the web app, open **New project**. Pick the repo and branch (install the GitHub App when asked), then **Connect and deploy**. The first deploy starts right away.
+4. Set the secrets your functions declare on the project page. After that, every push to the branch deploys.
+
+## Anatomy
+
+```python
+from datetime import date
+from typing import Literal
+
+from callables import deploy
+
+
+@deploy(title="Closed deals", secrets=["CRM_TOKEN"], timeout=120)
+def closed_deals(region: Literal["NA", "EMEA", "APAC"] = "NA", since: date | None = None,
+                 min_value: int = 0) -> list[dict]:
+    """Deals closed in a region, newest first.
+
+    Pulls from the CRM; amounts are in USD.
+    """
+    ...
+```
+
+- `name`: the function's identity on the platform. It defaults to the function name. **Renaming it creates a new automation**, and the old one's history and schedules stay behind. Pass `name="..."` to keep the identity if you rename the Python function.
+- `title`: the card and page heading. It defaults to the name, turned into a sentence.
+- `description`: the first paragraph of the docstring is the default. Write one plain-language sentence about what it does for the person.
+- `secrets`: names of environment variables, which builders set in the web app. Read them with `os.environ["CRM_TOKEN"]`. Never hard-code credentials and never take them as inputs. A declared secret that nobody has set doesn't block the run: the variable is simply missing, and builders see a "missing secrets" warning. For an optional secret, declare it and read it with `os.environ.get(...)`. Each secret is a single value, so a key file such as a `.pem` goes in as the file's contents, and the code reads it from the variable.
+- `timeout`: in seconds. The default is 300 and the maximum is 900.
+- `schedule`: a cron expression in UTC, for schedules owned by the code. Only use it when the user asks for one. Anyone can add a schedule in the web app, so you usually don't need it.
+
+## Groups: organise related functions
+
+A project (one repo) can hold many functions. Put related ones in a `Group`, like a Typer sub-app. People see them as one section of the project in the web app, and you run them as `call <group> <action>`.
+
+```python
+from typing import Literal
+
+from callables import Group
+
+backups = Group("backups", title="Database backups", description="Postgres dumps to object storage",
+                secrets=["SPACES_KEY", "SPACES_SECRET"])   # given to every action in the group
+
+
+@backups.deploy(title="Back up now", secrets=["DATABASE_URL"])
+def run(env: Literal["prod", "staging"] = "prod", keep: int = 7) -> str:
+    ...
+
+
+@backups.deploy(title="List backups")
+def list_all(days: int = 30) -> list[dict]:
+    ...
+```
+
+```bash
+call backups --help       # the group's actions
+call backups run --help   # flags, from the type hints
+call backups run --env staging --keep 3
+```
+
+- A group name is lowercase letters, digits, `-` or `_`, and can't be a built-in command (`check`, `local`, ...). Define each group once and import it wherever you need it.
+- An action's full name is `<group>.<name>`, e.g. `backups.run`. Use that with `call local`.
+- A function's name is its identity on the platform. Moving an existing function into a group gives it a new name, so it starts with fresh run history and sharing settings.
+- A plain `@deploy` still works. Those functions appear in the project without a section, and run as `call <name> --flags`.
+
+### Local commands
+
+Some tools only make sense on your own machine: they read local files, write reports to disk or open a browser. Write them with `@command` (or `@group.command`) instead of `@deploy`, so the project has one CLI and no separate Typer app:
+
+```python
+from callables import Group
+
+audits = Group("audits", title="Audits")
+
+
+@audits.command
+def render(slug: str, open_browser: bool = False) -> str:
+    ...
+```
+
+- They run as `call audits render --slug x` and with `call local`, with flags from the type hints, like any action. `call check` lists them as "(local only)".
+- They're never deployed: the platform doesn't see them and nobody can run them from the web app. `@command` takes `name`, `title`, `description` and `next`, but no `secrets`, `schedule` or `timeout`, because it runs in your own environment (read secrets from `.env`). A deployed action's `next=` can't point at one.
+- Their module is still imported when the platform builds, so keep imports that only work locally inside the function.
+- Return the result instead of printing it. The CLI prints what you return (a table as aligned columns in a terminal, JSON when piped), so printing it as well shows it twice. Keep prints for progress.
+- To deploy one later, change `@command` to `@deploy`. It keeps its name.
+
+## Flows: what to do next with a result
+
+Chain actions into step-by-step flows with `next=`. Each row of a table result (or a single dict/model result) offers the next actions, with their inputs filled in from that row. Every step is still an ordinary action: it can be run on its own, scheduled or shared separately.
+
+```python
+from typing import Literal
+
+from callables import Group, Next
+
+users = Group("users", title="Users")
+
+
+@users.deploy(title="Make admin")
+def make_admin(user_id: int) -> str: ...
+
+
+@users.deploy(title="Subscription requirement")
+def set_subscription(user_id: int, required: Literal["Required", "Not required"]) -> str: ...
+
+
+@users.deploy(title="Find user", next=[make_admin, Next(set_subscription, label="Change subscription", user_id="id")])
+def search(query: str) -> list[dict]:
+    return [{"id": 42, "user_id": 42, "name": "Ann Lee", "email": "ann@example.com"}]
+```
+
+- An action's inputs are filled from result fields with the same name. `Next(action, user_id="id")` maps a field with a different name, and `label=` changes the button text.
+- `next` takes deployed functions, or names (`"make_admin"`, or `"users.make_admin"` for another group's action) when the action is defined further down.
+- In the web app, each result row gets a button per next action. It opens that action's form with the row's values filled in, and the new run links back to the one it came from.
+- In a terminal, `call users search --query ann` lists the rows, asks which one and what to do next, prompts for the inputs the row didn't fill, and runs it. Press Enter to stop. Scripts and `--json` get plain output with no prompts.
+- People only see next actions they're allowed to run.
+
+## Inputs: type hints become the form
+
+| Type hint | Form field |
+|---|---|
+| `str` | text box |
+| `int`, `float` | number |
+| `bool` | checkbox |
+| `date`, `datetime` | date or date-time picker |
+| `Literal["a", "b"]` or an `Enum` | dropdown |
+| `list[str]` and so on | list editor |
+| `X \| None = None` | optional field |
+| a Pydantic model | grouped sub-form |
+| `File`, or `Annotated[File, accept(".csv")]` | file upload |
+
+- A default value makes the field optional and prefills it. A parameter without a default is required.
+- Parameter names become labels: `min_value` shows as "Min value". Choose names that read well.
+- Prefer `Literal[...]` over free text whenever the valid values are known.
+- Not supported: `*args`, `**kwargs`, `Callable` or arbitrary classes. `call check` names the offending parameter.
+- Avoid `dict` inputs. They show as a raw JSON box, so use a Pydantic model instead.
+- Inputs are validated and coerced before your function runs. A `date` arrives as a `datetime.date`, and a model arrives as an instance.
+
+## Results: the return type picks the display
+
+| Return annotation | Shown as |
+|---|---|
+| `-> str` | Markdown (headings, lists, links and tables work) |
+| `-> list[dict]`, a list of models, or a DataFrame | a table with CSV download |
+| `-> dict` or a Pydantic model | a key-value list |
+| `-> File` or `-> list[File]` | download buttons |
+| `-> None` | "Done" |
+| missing or anything else | raw JSON (avoid this) |
+
+Always annotate the return type. Keep table rows flat (scalar values) and use readable keys, because the keys become column headers.
+
+## Files
+
+```python
+from typing import Annotated
+
+from callables import File, accept, deploy, save_file
+
+
+@deploy(title="Clean up a contact list")
+def clean_contacts(sheet: Annotated[File, accept(".csv")]) -> File:
+    """Removes duplicate rows and fixes capitalisation."""
+    rows = sheet.read_text().splitlines()            # also: .read_bytes(), .open(), .path, .name, .size
+    save_file(f"{len(rows)} rows in".encode(), name="summary.txt")   # an extra download
+    out = "/tmp/clean.csv"
+    ...
+    return File(out, name=f"clean-{sheet.name}")
+```
+
+- A `File` parameter is an upload field. Use `accept(...)` to limit the file types.
+- Returning `File` gives the person a download. `save_file(path_or_bytes, name=...)` adds more downloads alongside any return value. It needs `name=` when you pass bytes.
+- Locally, pass a file with `-i sheet=@path/to/file.csv`. Outputs land in `./callables-output/`.
+- Limits: 100 MB per upload, and 100 MB and 20 files of output per run. Files are deleted after 24 hours.
+- Functions with file inputs can't be scheduled.
+
+## Runtime environment
+
+- Each run gets a fresh sandbox on Debian 13 (trixie). It runs as a non-root user and has internet access.
+- **Python version:** taken from `.python-version` (e.g. `3.13`), else the newest version your `pyproject.toml` `requires-python` allows, else 3.12. Supported: 3.10 to 3.14.
+- **Python dependencies** come from `requirements.txt` at the repo root, or from `[project].dependencies` in `pyproject.toml`. **Don't list `callables`.** The platform installs its own matching copy.
+- **Automations in a subfolder:** by default the whole repo is built. To build only one folder, add `callables.toml` at the repo root containing `root = "automations"` (or `[tool.callables] root = "automations"` in `pyproject.toml`). Then only that folder goes into the image, and its own `requirements.txt`, `apt.txt` and `.python-version` are used. Code in it can't import from the rest of the repo. `call check`, `local` and `manifest` use the same folder when run from the repo root.
+- **Writable space:** your home directory (`~`), and `/tmp`, which is limited to 256 MB. Your code in `/app` is read-only. Every run starts fresh, so nothing persists between runs. Keep state in your own database or storage.
+- **Running downloaded binaries:** `/tmp` doesn't allow running programs, so a binary downloaded there fails with `Permission denied`. Put it under `~` and `chmod +x` it. Better still, install the tool with `apt.txt` (below).
+- Every module that imports `callables` and mentions `deploy` is imported at build time. Keep import-time code cheap and free of side effects: no network calls, and no reading secrets at module level. Read secrets inside the function.
+- `print()` output and `logging` show as the run's logs. Tracebacks are shown only to builders, never to the person running the automation.
+
+## System packages
+
+When a function shells out to a command-line tool (a converter, a database client, a headless browser), list the Debian packages it needs in `apt.txt` at the repo root:
+
+```
+# apt.txt: one package per line
+ffmpeg
+poppler-utils
+```
+
+- Names only, no versions. You get the version Debian 13 (trixie) ships, which stays the same apart from security fixes. If the tool talks to an outside service, check that this version works with it.
+- Packages are installed without their "recommended" extras. If a tool is missing something (fonts, for example), list that package too.
+- They're installed once per change to `apt.txt`, not on every push.
+- `call local` uses the tools on your own machine, so install them there too to test.
+
+## Memory and CPU
+
+You don't size anything. A run can use memory and CPU up to your organisation's plan limit, and usage is billed on what the run actually used, not on the limit. Builders see each run's peak memory and CPU time on its page.
+
+If a run goes over the memory limit, it fails with an error that says so. Fix it by using less memory (process files in chunks, stream instead of loading everything, free large objects you're done with), or move to a bigger plan. Child processes count toward the same limit.
+
+## Errors people will see
+
+Raise exceptions with messages written for the person running the automation. They see `ValueError: No deals found for EMEA since 2026-01-01`, so make it say what to change. For bad input, raise `ValueError` with a message about that field.
+
+## Commands
+
+- `call check [--json]`: problems a deploy would hit, with fixes. Exit code 1 on errors.
+- `call <group> <action> [--flags]` (or `call <function> [--flags]`): run a function like a CLI command. Each input is a flag (`days` becomes `--days`, a bool becomes `--dry-run/--no-dry-run`, a list takes several values). Add `--help` to see them.
+- `call local <name> [-i key=value ...] [--json]`: run a function on this machine. Values are parsed as JSON when possible, and `@path` passes a file. `--json` prints one JSON object on stdout (`ok`, `value`, `files`, `error`, `field_errors`), and the function's own prints go to stderr.
+- `call manifest`: the full JSON the platform reads, including each input's JSON Schema. Local `@command`s are left out.
+- `call docs`: prints this guide.
+- `call init`: an example automation plus agent instructions (`.claude/skills/callables/SKILL.md` and an `AGENTS.md` section). Run it again after upgrading the SDK to refresh the instructions.

callables-0.1.0/callables/__init__.py

@@ -0,0 +1,6 @@
+"""Callables SDK: mark functions with @deploy and push the repo; the platform does the rest."""
+from callables.decorator import DeployedFunction, Group, Next, command, deploy, registry
+from callables.files import File, accept, save_file
+
+__version__ = "0.1.0"
+__all__ = ["deploy", "command", "Group", "Next", "DeployedFunction", "registry", "File", "accept", "save_file", "__version__"]

callables-0.1.0/callables/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from callables.cli import main
+
+sys.exit(main())

callables-0.1.0/callables/checks.py

@@ -0,0 +1,110 @@
+"""`call check`: the problems a deploy would hit, found on this machine before pushing.
+
+Errors match what makes the platform reject a deploy; warnings match what it would ignore or cap.
+"""
+import inspect
+import re
+from pathlib import Path
+from typing import Any
+
+from callables.decorator import registry
+from callables.files import FILE_FORMAT
+from callables.manifest import build_manifest
+
+MAX_TIMEOUT = 900  # the platform caps timeouts here
+SECRET_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+CRON_FIELD = re.compile(r"^[\d*/,\-A-Za-z?]+$")
+
+
+def _issue(level: str, message: str, function: str | None = None, fix: str | None = None) -> dict[str, Any]:
+    issue: dict[str, Any] = {"level": level, "message": message}
+    if function:
+        issue["function"] = function
+    if fix:
+        issue["fix"] = fix
+    return issue
+
+
+def _file_fields(schema: dict[str, Any]) -> list[str]:
+    return [
+        name for name, prop in (schema.get("properties") or {}).items()
+        if any(o.get("format") == FILE_FORMAT for o in [prop, *prop.get("anyOf", [])])
+    ]
+
+
+def _check_function(fn: dict[str, Any]) -> list[dict[str, Any]]:
+    name, issues = fn["name"], []
+    schema = fn["input_schema"]
+    deployed = registry.get(name)
+
+    if not fn.get("description") and not fn.get("local_only"):
+        issues.append(_issue("warning", "No description; people see a blank card", name,
+                             "Add a docstring: its first paragraph becomes the description"))
+    if deployed is not None:
+        untyped = [p for p in inspect.signature(deployed.func).parameters if p not in deployed.func.__annotations__]
+        for param in untyped:
+            issues.append(_issue("warning", f"Parameter '{param}' has no type hint, so it's a plain text field", name,
+                                 f"Annotate it, e.g. `{param}: int` or `{param}: Literal['a', 'b']`"))
+        if "return" not in deployed.func.__annotations__:
+            issues.append(_issue("warning", "No return type, so the result is shown as raw JSON", name,
+                                 "Annotate the return: -> str (Markdown), -> list[dict] (table), -> dict (key-value), "
+                                 "-> File (download) or -> None"))
+
+    if fn["timeout"] > MAX_TIMEOUT:
+        issues.append(_issue("warning", f"timeout={fn['timeout']} is above the {MAX_TIMEOUT}s limit and will be capped",
+                             name, f"Use timeout={MAX_TIMEOUT} or less"))
+    elif fn["timeout"] <= 0:
+        issues.append(_issue("error", "timeout must be a positive number of seconds", name))
+
+    for secret in fn.get("secrets") or []:
+        if not SECRET_NAME.match(secret):
+            issues.append(_issue("error", f"Secret name '{secret}' isn't a valid environment variable name", name,
+                                 "Use letters, digits and underscores, e.g. SALES_API_TOKEN"))
+
+    if fn.get("next") and fn["output_kind"] not in ("table", "kv"):
+        issues.append(_issue("warning", "next actions are offered on table rows or a single record, so they won't "
+                             "show for this result", name, "Return list[dict] (rows) or a dict/model (one record)"))
+
+    schedule = fn.get("schedule")
+    if schedule:
+        fields = schedule.split()
+        if len(fields) != 5 or not all(CRON_FIELD.match(f) for f in fields):
+            issues.append(_issue("warning", f"schedule '{schedule}' isn't a 5-field cron expression and will be ignored",
+                                 name, "e.g. schedule='0 9 * * MON' (minute hour day month weekday, UTC)"))
+        if schema.get("required"):
+            issues.append(_issue("warning", "Scheduled functions need a default for every input; the schedule will "
+                                 f"be ignored (no default: {', '.join(schema['required'])})", name))
+        if _file_fields(schema):
+            issues.append(_issue("warning", "Functions with file inputs can't run on a schedule", name,
+                                 "Drop the schedule, or read the file from storage instead of an upload"))
+    return issues
+
+
+def check_project(root: Path) -> dict[str, Any]:
+    manifest = build_manifest(root, include_local=True)
+    issues = []
+    for err in manifest["errors"]:
+        where = err.get("module") or err.get("function")
+        issues.append(_issue("error", f"{where}: {err['error']}", err.get("function"),
+                             "Fix this first: if any module fails to import, the platform publishes nothing"))
+    if not manifest["functions"] and not manifest["errors"]:
+        issues.append(_issue("error", "No @deploy functions found",
+                             fix="Decorate a function: `from callables import deploy` then `@deploy` above `def ...`"))
+    elif manifest["functions"] and all(f.get("local_only") for f in manifest["functions"]):
+        issues.append(_issue("warning", "Every function is a local @command, so a deploy publishes nothing",
+                             fix="Use @deploy for anything teammates should run"))
+    for fn in manifest["functions"]:
+        issues.extend(_check_function(fn))
+    if not (Path(root) / "requirements.txt").is_file() and not (Path(root) / "pyproject.toml").is_file():
+        issues.append(_issue("warning", "No requirements.txt, so only the standard library is installed",
+                             fix="List your dependencies (not callables itself) in requirements.txt"))
+    return {
+        "ok": not any(i["level"] == "error" for i in issues),
+        "functions": [
+            {"name": f["name"], "title": f["title"], "entrypoint": f["entrypoint"],
+             "inputs": f["input_schema"].get("x-order", []), "output_kind": f["output_kind"],
+             "local_only": bool(f.get("local_only"))}
+            for f in manifest["functions"]
+        ],
+        "issues": issues,
+    }