formist-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
formist_cli/targets.py ADDED
@@ -0,0 +1,153 @@
1
+ """Which deployment a command talks to.
2
+
3
+ ``fm`` talks to ``https://api.formist.ai`` unless ``--host`` names another
4
+ deployment. ``--host`` takes either a name from :data:`HOSTS` or an API origin
5
+ (``https://api.example.com``, ``127.0.0.1:8160``) for a custom deployment.
6
+
7
+ Spaces are addressed by UUID, never by name: names are not unique, so a name can
8
+ silently pick the wrong space.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import re
14
+ from dataclasses import dataclass
15
+ from urllib.parse import urlparse
16
+
17
+ #: Deployment kinds. ``env`` on a :class:`Target` is one of these; it decides how
18
+ #: the server is expected to behave (multi-region admin routing, local dev), not
19
+ #: where credentials are stored (that is :attr:`Target.name`).
20
+ REGION_LOCAL = "local"
21
+ REGION_GLOBAL = "global"
22
+ REGION_AE = "ae"
23
+ REGION_FORMIST = "formist"
24
+ REGION_CUSTOM = "custom"
25
+
26
+ VALID_ENVS = (REGION_LOCAL, REGION_AE, REGION_GLOBAL, REGION_FORMIST, REGION_CUSTOM)
27
+
28
+ #: Deployments that serve the whole ``/admin`` surface themselves. A regional
29
+ #: Evane host (``evane-ae``) serves only a region-local subset and answers 410
30
+ #: for the rest.
31
+ ADMIN_ONLY_ENVS = (REGION_GLOBAL, REGION_FORMIST, REGION_CUSTOM)
32
+
33
+ DEFAULT_HOST = "formist"
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class HostSpec:
38
+ """One named deployment."""
39
+
40
+ name: str
41
+ api_base: str
42
+ env: str
43
+ product: str
44
+ description: str
45
+
46
+
47
+ HOSTS: dict[str, HostSpec] = {
48
+ "formist": HostSpec(
49
+ "formist", "https://api.formist.ai", REGION_FORMIST, "Formist", "Formist"
50
+ ),
51
+ "evane": HostSpec(
52
+ "evane", "https://api.evane.ai", REGION_GLOBAL, "Evane", "Evane, Global region"
53
+ ),
54
+ "evane-ae": HostSpec(
55
+ "evane-ae", "https://ae.api.evane.ai", REGION_AE, "Evane", "Evane, UAE region"
56
+ ),
57
+ "formist-cn": HostSpec(
58
+ "formist-cn",
59
+ "https://formist-api.we-carbon.com",
60
+ REGION_FORMIST,
61
+ "Formist",
62
+ "Formist China",
63
+ ),
64
+ }
65
+
66
+ _UUID_RE = re.compile(
67
+ r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
68
+ )
69
+ _LOOPBACK = {"127.0.0.1", "localhost", "::1"}
70
+
71
+
72
+ class TargetError(Exception):
73
+ """A refusal to point at something. The message is written for the user."""
74
+
75
+
76
+ @dataclass(frozen=True)
77
+ class Target:
78
+ """A resolved destination.
79
+
80
+ ``name`` keys the stored credential and is what the user typed (or the
81
+ default); ``env`` is the deployment kind (see :data:`VALID_ENVS`).
82
+ """
83
+
84
+ env: str
85
+ api_base: str
86
+ name: str = DEFAULT_HOST
87
+ product: str | None = None
88
+
89
+ @property
90
+ def is_prod(self) -> bool:
91
+ return self.env != REGION_LOCAL
92
+
93
+
94
+ def is_admin_env(env: str) -> bool:
95
+ """True when a deployment of kind ``env`` serves ``/admin`` itself."""
96
+ return env in ADMIN_ONLY_ENVS
97
+
98
+
99
+ def host_names() -> tuple[str, ...]:
100
+ return tuple(HOSTS)
101
+
102
+
103
+ def _custom(value: str) -> Target:
104
+ parsed = urlparse(value if "://" in value else f"//{value}", scheme="")
105
+ host = (parsed.hostname or "").lower()
106
+ if not host or parsed.path not in ("", "/") or parsed.query or parsed.fragment:
107
+ raise TargetError(
108
+ f"--host {value!r} is neither a known deployment "
109
+ f"({', '.join(HOSTS)}) nor an API origin such as "
110
+ "https://api.example.com or 127.0.0.1:8160."
111
+ )
112
+ loopback = host in _LOOPBACK
113
+ scheme = parsed.scheme or ("http" if loopback else "https")
114
+ if scheme not in ("http", "https"):
115
+ raise TargetError(f"--host {value!r}: only http and https are supported.")
116
+ netloc = f"{host}:{parsed.port}" if parsed.port else host
117
+ if ":" in host:
118
+ netloc = f"[{host}]:{parsed.port}" if parsed.port else f"[{host}]"
119
+ return Target(
120
+ env=REGION_LOCAL if loopback else REGION_CUSTOM,
121
+ api_base=f"{scheme}://{netloc}",
122
+ name=netloc,
123
+ )
124
+
125
+
126
+ def resolve(host: str | None) -> Target:
127
+ """Resolve ``--host`` to a :class:`Target`. ``None`` means :data:`DEFAULT_HOST`."""
128
+ value = (host or DEFAULT_HOST).strip()
129
+ if not value:
130
+ value = DEFAULT_HOST
131
+ spec = HOSTS.get(value.lower())
132
+ if spec is None:
133
+ return _custom(value)
134
+ return Target(env=spec.env, api_base=spec.api_base, name=spec.name, product=spec.product)
135
+
136
+
137
+ def check_api_base(url: str) -> None:
138
+ """Refuse a base URL that has no hostname."""
139
+ parsed = urlparse(url if "://" in url else f"//{url}")
140
+ if not parsed.hostname:
141
+ raise TargetError(f"could not read a hostname out of {url!r}")
142
+
143
+
144
+ def require_space_id(value: str) -> str:
145
+ """A space is addressed by its UUID, never by name."""
146
+ value = value.strip()
147
+ if not _UUID_RE.match(value):
148
+ raise TargetError(
149
+ f"--space needs a space id (a UUID), got {value!r}. fm never looks a "
150
+ "space up by name, because names are not unique. Find the id with "
151
+ "`fm spaces`."
152
+ )
153
+ return value
@@ -0,0 +1,26 @@
1
+ """Character tables used to normalise text before comparing it.
2
+
3
+ ``fm diff`` and ``fm ai-benchmark`` both decide whether two pieces of
4
+ text are the same, under different rules: ``diff`` matches a source
5
+ row against a database row to decide a write, and is case-sensitive,
6
+ since folding case can match the wrong row. ``ai-benchmark`` looks for
7
+ an expected string inside a model's prose answer, and folds case. The
8
+ two commands keep separate comparison rules but share the same
9
+ Unicode facts: which characters are a space, a quote, or a dash.
10
+
11
+ Stdlib only: this module must not add a runtime dependency.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ #: Unicode spaces mapped to U+0020. A bare ``.strip()`` already removes
17
+ #: most of these; the table is load-bearing for U+200B and U+FEFF,
18
+ #: which are ``isspace()``-false, unmatched by ``\s``, and untouched by
19
+ #: NFKC.
20
+ SPACES = "  ​"
21
+
22
+ #: Curly quotes and the prime, mapped to their straight equivalents.
23
+ QUOTES = {"‘": "'", "’": "'", "“": '"', "”": '"', "′": "'"}
24
+
25
+ #: En/em/figure/non-breaking dashes and the minus sign, mapped to ``-``.
26
+ DASHES = {"‐": "-", "‑": "-", "‒": "-", "–": "-", "—": "-", "−": "-"}
formist_cli/tokens.py ADDED
@@ -0,0 +1,339 @@
1
+ """Session-token storage for ``fm``: on disk at 0600, never on a terminal.
2
+
3
+ A token that has to be handed around by hand ends up in scrollback, in
4
+ history, and in transcripts. ``fm login`` puts it in a file only this
5
+ user can read; ``fm logout`` removes it. Nothing here ever prints a
6
+ token, and :func:`describe_meta` deliberately returns metadata rather
7
+ than the credential.
8
+
9
+ The file is per-environment, so a local token can never be sent to prod
10
+ by accident: the target picks the file, not the other way round.
11
+
12
+ The access token itself is opaque (``crst_at_...``): since ``fm login``
13
+ is an OAuth client there is nothing in it to decode, which is exactly
14
+ what makes it revocable. Anything worth reporting about a stored
15
+ credential (expiry, scopes, who issued it) was already written to the
16
+ metadata beside it at the moment ``fm login``/refresh minted it
17
+ (:func:`formist_cli.login.store_payload`); see :func:`describe_meta`,
18
+ which reads that instead of the token.
19
+
20
+ The one exception to "on disk, never on a terminal" is ``$EVANE_TOKEN``
21
+ (see :func:`env_token`): one credential environment variable, for CI and
22
+ unattended machines that have no browser to run ``fm login`` in. It is
23
+ read fresh on every invocation, wins over whatever is on disk for that
24
+ call, and is never written to a file and never refreshed; a CI token
25
+ that expires gets re-issued by whoever owns it, the same as the
26
+ file-based one needs a fresh ``fm login`` after 30 days.
27
+ """
28
+
29
+ from __future__ import annotations
30
+
31
+ import json
32
+ import os
33
+ import re
34
+ import stat
35
+ from dataclasses import dataclass
36
+ from datetime import datetime, timezone
37
+ from pathlib import Path
38
+
39
+
40
+ class TokenError(Exception):
41
+ """Something wrong with a stored credential. Never contains the credential."""
42
+
43
+
44
+ CONFIG_DIR_VAR = "FORMIST_CONFIG_DIR"
45
+
46
+
47
+ def config_dir() -> Path:
48
+ """``$FORMIST_CONFIG_DIR``, else ``$XDG_CONFIG_HOME/formist``, else ``~/.config/formist``.
49
+
50
+ Public, and the only implementation: this resolves where the
51
+ credentials live, and a second copy of this logic elsewhere would risk
52
+ `fm logout` one day clearing a directory that `fm login` did not write
53
+ to, with the symptom being a token that survives a logout.
54
+ """
55
+ explicit = os.environ.get(CONFIG_DIR_VAR)
56
+ if explicit:
57
+ return Path(explicit).expanduser()
58
+ xdg = os.environ.get("XDG_CONFIG_HOME")
59
+ base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
60
+ return base / "formist"
61
+
62
+
63
+ def _file_key(name: str) -> str:
64
+ """A host name or ``host:port`` as a safe file-name component."""
65
+ return re.sub(r"[^A-Za-z0-9._-]", "_", name)
66
+
67
+
68
+ def token_path(env: str) -> Path:
69
+ """The credential file for one host (``env`` is :attr:`Target.name`)."""
70
+ return config_dir() / f"token-{_file_key(env)}.json"
71
+
72
+
73
+ #: The one credential environment variable this CLI reads.
74
+ ENV_TOKEN_VAR = "FORMIST_TOKEN"
75
+
76
+ #: The origin :func:`load_for` reports when the credential came from
77
+ #: :data:`ENV_TOKEN_VAR` rather than any environment's file. Never equal to a real
78
+ #: env name (``local`` / ``global`` / ``ae``), so ``origin == env`` (the
79
+ #: "not borrowed from another region" check callers already do) stays correct
80
+ #: unchanged.
81
+ ENV_TOKEN_ORIGIN = "env"
82
+
83
+
84
+ def _looks_like_a_session_jwt(value: str) -> bool:
85
+ """True for a 3-segment dot-separated value, the shape an old pasted-browser
86
+ credential had. An `fm login` token is opaque (``crst_at_...``, no dots at
87
+ all), so this shape is never a legitimate value here.
88
+
89
+ Refusing it is the one guard code can actually run: `fm` cannot tell a stolen
90
+ *opaque* token from a legitimate one (that is what "opaque" means), but it can
91
+ tell that a JWT landed in the wrong variable, which would hand `fm` a 7-day
92
+ whole-account credential instead of the scoped, revocable one the OAuth flow
93
+ exists to provide.
94
+ """
95
+ parts = value.split(".")
96
+ return len(parts) == 3 and all(parts)
97
+
98
+
99
+ def env_token() -> str:
100
+ """``$EVANE_TOKEN``, stripped; ``""`` when unset or blank.
101
+
102
+ Raises :class:`TokenError` rather than silently ignoring a JWT-shaped
103
+ value, so a CI job that exported the wrong secret gets one clear
104
+ message instead of a hard-to-place 401 (or worse, a working-but-wrong
105
+ request against someone else's session).
106
+ """
107
+ raw = (os.environ.get(ENV_TOKEN_VAR) or "").strip()
108
+ if raw and _looks_like_a_session_jwt(raw):
109
+ raise TokenError(
110
+ f"{ENV_TOKEN_VAR} looks like a browser session token (three "
111
+ "dot-separated segments), not an `fm login` credential. `fm login` "
112
+ "tokens are opaque and never contain a dot. Mint one with `fm login` "
113
+ "and export the 'token' field of the file it writes "
114
+ f"({token_path('<env>')}) instead."
115
+ )
116
+ return raw
117
+
118
+
119
+ def local_scopes(env: str) -> list | None:
120
+ """The scopes ``fm`` can claim to know about ``env``'s credential, for
121
+ :func:`formist_cli.privileges.check`'s LOCAL pre-flight ONLY.
122
+
123
+ ``None`` whenever :data:`ENV_TOKEN_VAR` is set: an env-sourced token is opaque
124
+ and this process never learns what it was granted, so a FILE's recorded scopes
125
+ (if one happens to exist for the same env) describe a DIFFERENT credential than
126
+ the one actually in use and must not be consulted. ``privileges.check`` already
127
+ treats ``None`` as "not recorded, defer to the server", the correct answer
128
+ here too, and the same answer an operator who never logged in locally at all
129
+ would get.
130
+ """
131
+ if env_token():
132
+ return None
133
+ return load_meta(env).get("scopes")
134
+
135
+
136
+ def store(env: str, token: str, meta: dict | None = None) -> Path:
137
+ """Write ``token`` for ``env`` at 0600, creating the directory at 0700.
138
+
139
+ The mode is set BEFORE the write where the platform allows it (``os.open``
140
+ with the mode argument), so the secret is never briefly world-readable;
141
+ a chmod after the fact leaves a window.
142
+
143
+ ``meta`` holds what `fm login` learned at the same moment: the ``refresh_token``
144
+ (a secret, and the reason this whole file is 0600), the granted ``scopes``, the
145
+ absolute ``expires_at``, and the ``client_id`` / ``grant_id`` `fm logout` needs
146
+ in order to revoke server-side. They live in the same file rather than a second
147
+ one because they describe THIS credential: a metadata file that could outlive
148
+ its token, or be swapped for another environment's, is a way to revoke the wrong
149
+ thing. :func:`load_meta` never returns either secret.
150
+ """
151
+ directory = config_dir()
152
+ directory.mkdir(parents=True, exist_ok=True)
153
+ os.chmod(directory, stat.S_IRWXU) # 0700
154
+
155
+ path = token_path(env)
156
+ payload = json.dumps(
157
+ {"env": env, "token": token, "stored_at": _now_iso(), **(meta or {})}, indent=2
158
+ )
159
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR)
160
+ try:
161
+ os.write(fd, payload.encode())
162
+ finally:
163
+ os.close(fd)
164
+ os.chmod(path, stat.S_IRUSR | stat.S_IWUSR) # 0600, belt and braces
165
+ return path
166
+
167
+
168
+ def _refuse_loose_permissions(path: Path, env: str) -> None:
169
+ """Refuse a credential file anyone else can read.
170
+
171
+ Its own function because the file now holds TWO secrets (the access token and
172
+ the refresh token) read by two callers, and a permission check that guarded one
173
+ of them would be a check that cannot fail for the other.
174
+ """
175
+ mode = path.stat().st_mode
176
+ if mode & (stat.S_IRWXG | stat.S_IRWXO):
177
+ raise TokenError(
178
+ f"{path} is readable by others (mode {stat.filemode(mode)}). "
179
+ "Refusing to use it. Run `fm logout --env "
180
+ f"{env}` and `fm login --host {env}` to replace it."
181
+ )
182
+
183
+
184
+ def load(env: str) -> str | None:
185
+ """The stored token for ``env``, or None. Refuses a file with loose permissions."""
186
+ path = token_path(env)
187
+ if not path.exists():
188
+ return None
189
+ _refuse_loose_permissions(path, env)
190
+ try:
191
+ return json.loads(path.read_text()).get("token") or None
192
+ except (json.JSONDecodeError, OSError) as exc:
193
+ raise TokenError(f"could not read {path}: {exc}") from exc
194
+
195
+
196
+ def load_meta(env: str) -> dict:
197
+ """The non-secret facts stored beside the credential. Never the credential.
198
+
199
+ Returns ``{}`` when there is no file, when it is unreadable, or when it was
200
+ written by a pre-``fm login``-flow version that stored only a token: a missing
201
+ ``token_id`` must degrade to "revoke whatever credential this request carries",
202
+ not to a crash.
203
+ """
204
+ path = token_path(env)
205
+ if not path.exists():
206
+ return {}
207
+ try:
208
+ data = json.loads(path.read_text())
209
+ except (json.JSONDecodeError, OSError):
210
+ return {}
211
+ if not isinstance(data, dict):
212
+ return {}
213
+ return {k: v for k, v in data.items() if k not in ("token", "refresh_token")}
214
+
215
+
216
+ def load_refresh(env: str) -> str | None:
217
+ """The stored refresh token, or None. Same 0600 refusal as :func:`load`.
218
+
219
+ Separate from :func:`load_meta` on purpose: this is a secret, it buys a fresh
220
+ access token for as long as the grant lives, so it is never in the dict that
221
+ gets printed, logged or handed to `fm whoami`.
222
+ """
223
+ path = token_path(env)
224
+ if not path.exists():
225
+ return None
226
+ _refuse_loose_permissions(path, env)
227
+ try:
228
+ return json.loads(path.read_text()).get("refresh_token") or None
229
+ except (json.JSONDecodeError, OSError) as exc:
230
+ raise TokenError(f"could not read {path}: {exc}") from exc
231
+
232
+
233
+ def clear(env: str) -> bool:
234
+ """Remove the stored token for ``env``. True if there was one."""
235
+ path = token_path(env)
236
+ if not path.exists():
237
+ return False
238
+ path.unlink()
239
+ return True
240
+
241
+
242
+ def clear_all() -> list[str]:
243
+ """Remove every stored token. Returns the environments that had one."""
244
+ directory = config_dir()
245
+ if not directory.exists():
246
+ return []
247
+ removed = []
248
+ for path in sorted(directory.glob("token-*.json")):
249
+ removed.append(path.stem.removeprefix("token-"))
250
+ path.unlink()
251
+ return removed
252
+
253
+
254
+ @dataclass(frozen=True)
255
+ class TokenInfo:
256
+ """Non-secret facts about a stored token, as recorded in its metadata,
257
+ never decoded from the token (see :func:`describe_meta`)."""
258
+
259
+ expires_at: datetime | None
260
+ issued_at: datetime | None
261
+
262
+ @property
263
+ def expired(self) -> bool:
264
+ return self.expires_at is not None and self.expires_at <= _utcnow()
265
+
266
+ def describe_expiry(self) -> str:
267
+ if self.expires_at is None:
268
+ return "no expiry recorded"
269
+ delta = self.expires_at - _utcnow()
270
+ if delta.total_seconds() <= 0:
271
+ return f"EXPIRED at {self.expires_at.isoformat()}"
272
+ hours = int(delta.total_seconds() // 3600)
273
+ return f"valid for ~{hours}h (until {self.expires_at.isoformat()})"
274
+
275
+
276
+ def describe_meta(meta: dict) -> TokenInfo:
277
+ """Non-secret facts about a stored credential, read from :func:`load_meta`,
278
+ never by decoding the token itself.
279
+
280
+ An ``fm login`` access token is opaque (``crst_at_...``, no dots at
281
+ all), so there is nothing in it to decode. Everything worth reporting
282
+ was already written beside the token at the moment it was minted or
283
+ refreshed (:func:`formist_cli.login.store_payload`): ``expires_at`` and
284
+ ``obtained_at``, so this reads that instead of guessing at the token's
285
+ shape.
286
+ """
287
+ return TokenInfo(
288
+ expires_at=_parse_iso(meta.get("expires_at")),
289
+ issued_at=_parse_iso(meta.get("obtained_at")),
290
+ )
291
+
292
+
293
+ def _parse_iso(value: object) -> datetime | None:
294
+ if not isinstance(value, str) or not value:
295
+ return None
296
+ try:
297
+ return datetime.fromisoformat(value)
298
+ except ValueError:
299
+ return None
300
+
301
+
302
+ def _utcnow() -> datetime:
303
+ return datetime.now(timezone.utc)
304
+
305
+
306
+ def _now_iso() -> str:
307
+ return _utcnow().isoformat()
308
+
309
+
310
+ #: The Evane regions are one deployment with one sign-in: a token minted on either
311
+ #: host is accepted by both. Every other host keeps its own credential.
312
+ _SHARED_SECRET_ENVS = frozenset({"evane", "evane-ae"})
313
+
314
+
315
+ def load_for(env: str) -> tuple[str | None, str | None]:
316
+ """The token to use for ``env``, and where it came from.
317
+
318
+ ``$EVANE_TOKEN`` (:data:`ENV_TOKEN_VAR`) is checked first and, when set, wins
319
+ over any stored file for THIS call; the origin comes back as
320
+ :data:`ENV_TOKEN_ORIGIN`, never a real env name, so a caller comparing
321
+ ``origin == env`` (the cross-region-borrow check) is unaffected.
322
+
323
+ Absent that, falling back between the prod regions saves a second `fm login`
324
+ for one credential. The origin is returned rather than hidden so the caller can
325
+ print it: a credential silently sourced from somewhere else is exactly the
326
+ kind of invisible state this tool is otherwise built to refuse.
327
+ """
328
+ env_value = env_token()
329
+ if env_value:
330
+ return env_value, ENV_TOKEN_ORIGIN
331
+ direct = load(env)
332
+ if direct:
333
+ return direct, env
334
+ if env in _SHARED_SECRET_ENVS:
335
+ for other in sorted(_SHARED_SECRET_ENVS - {env}):
336
+ borrowed = load(other)
337
+ if borrowed:
338
+ return borrowed, other
339
+ return None, None